Bug 1351426 - Part 5: Cleanup style and comments r=kip

MozReview-Commit-ID: HOPY8v4UWKo

--HG--
extra : rebase_source : 10ab05870a958d83bb4abf26343b8195d78225ce

gfx/2d/Polygon.h

@@ -17,6 +17,10 @@
 namespace mozilla {
 namespace gfx {
 
+/**
+ * Calculates the w = 0 intersection point for the edge defined by
+ * |aFirst| and |aSecond|.
+ */
 template<class Units>
 Point4DTyped<Units>
 CalculateEdgeIntersect(const Point4DTyped<Units>& aFirst,
@@ -59,6 +63,10 @@ ClipPointsAtInfinity(const nsTArray<Point4DTyped<Units>>& aPoints)
   return outPoints;
 }
 
+/**
+ * Calculates the distances between the points in |aPoints| and the plane
+ * defined by |aPlaneNormal| and |aPlanePoint|.
+ */
 template<class Units>
 nsTArray<float>
 CalculatePointPlaneDistances(const nsTArray<Point4DTyped<Units>>& aPoints,
@@ -146,7 +154,9 @@ ClipPointsWithPlane(const nsTArray<Point4DTyped<Units>>& aPoints,
   }
 }
 
-// PolygonTyped stores the points of a convex planar polygon.
+/**
+ * PolygonTyped stores the points of a convex planar polygon.
+ */
 template<class Units>
 class PolygonTyped {
   typedef Point3DTyped<Units> Point3DType;
@@ -172,6 +182,9 @@ public:
 #endif
   }
 
+  /**
+   * Returns the smallest 2D rectangle that can fully cover the polygon.
+   */
   RectTyped<Units> BoundingBox() const
   {
     if (mPoints.IsEmpty()) {
@@ -193,7 +206,9 @@ public:
     return RectTyped<Units>(minX, minY, maxX - minX, maxY - minY);
   }
 
-  // Clips the polygon against the given 2D rectangle.
+  /**
+   * Clips the polygon against the given 2D rectangle.
+   */
   PolygonTyped<Units> ClipPolygon(const RectTyped<Units>& aRect) const
   {
     if (aRect.IsEmpty()) {
@@ -203,7 +218,9 @@ public:
     return ClipPolygon(FromRect(aRect));
   }
 
-  // Clips this polygon against the given polygon in 2D.
+  /**
+   * Clips this polygon against |aPolygon| in 2D and returns a new polygon.
+   */
   PolygonTyped<Units> ClipPolygon(const PolygonTyped<Units>& aPolygon) const
   {
     const nsTArray<Point4DType>& points = aPolygon.GetPoints();
@@ -251,6 +268,9 @@ public:
     return PolygonTyped<Units>(Move(clippedPoints), mNormal);
   }
 
+  /**
+   * Returns a new polygon containing the bounds of the given 2D rectangle.
+   */
   static PolygonTyped<Units> FromRect(const RectTyped<Units>& aRect)
   {
     nsTArray<Point4DType> points {
@@ -279,6 +299,9 @@ public:
     return mPoints.Length() < 3;
   }
 
+  /**
+   * Returns a list of triangles covering the polygon.
+   */
   nsTArray<TriangleTyped<Units>> ToTriangles() const
   {
     nsTArray<TriangleTyped<Units>> triangles;
@@ -287,10 +310,11 @@ public:
       return triangles;
     }
 
+    // This fan triangulation method only works for convex polygons.
     for (size_t i = 1; i < mPoints.Length() - 1; ++i) {
       TriangleTyped<Units> triangle(Point(mPoints[0].x, mPoints[0].y),
                                     Point(mPoints[i].x, mPoints[i].y),
-                                    Point(mPoints[i+1].x, mPoints[i+1].y));
+                                    Point(mPoints[i + 1].x, mPoints[i + 1].y));
       triangles.AppendElement(Move(triangle));
     }
 

gfx/layers/BSPTree.h

@@ -19,16 +19,18 @@ namespace layers {
 
 class Layer;
 
-// Represents a layer that might have a non-rectangular geometry.
+/**
+ * Represents a layer that might have a non-rectangular geometry.
+ */
 struct LayerPolygon {
-  explicit LayerPolygon(Layer *aLayer)
+  explicit LayerPolygon(Layer* aLayer)
     : layer(aLayer) {}
 
-  LayerPolygon(Layer *aLayer,
+  LayerPolygon(Layer* aLayer,
                gfx::Polygon&& aGeometry)
     : layer(aLayer), geometry(Some(Move(aGeometry))) {}
 
-  LayerPolygon(Layer *aLayer,
+  LayerPolygon(Layer* aLayer,
                nsTArray<gfx::Point4D>&& aPoints,
                const gfx::Point4D& aNormal)
     : layer(aLayer)
@@ -36,7 +38,7 @@ struct LayerPolygon {
     geometry.emplace(Move(aPoints), aNormal);
   }
 
-  Layer *layer;
+  Layer* layer;
   Maybe<gfx::Polygon> geometry;
 };
 
@@ -48,9 +50,11 @@ struct LayerPolygon {
  */
 typedef mozilla::ArenaAllocator<4096, 8> BSPTreeArena;
 
-// Represents a node in a BSP tree. The node contains at least one layer with
-// associated geometry that is used as a splitting plane, and at most two child
-// nodes that represent the splitting planes that further subdivide the space.
+/**
+* Represents a node in a BSP tree. The node contains at least one layer with
+* associated geometry that is used as a splitting plane, and at most two child
+* nodes that represent the splitting planes that further subdivide the space.
+*/
 struct BSPTreeNode {
   BSPTreeNode()
     : front(nullptr), back(nullptr) {}
@@ -72,13 +76,15 @@ struct BSPTreeNode {
   std::list<LayerPolygon> layers;
 };
 
-// BSPTree class takes a list of layers as an input and uses binary space
-// partitioning algorithm to create a tree structure that can be used for
-// depth sorting.
-//
-// Sources for more information:
-// https://en.wikipedia.org/wiki/Binary_space_partitioning
-// ftp://ftp.sgi.com/other/bspfaq/faq/bspfaq.html
+/**
+ * BSPTree class takes a list of layers as an input and uses binary space
+ * partitioning algorithm to create a tree structure that can be used for
+ * depth sorting.
+
+ * Sources for more information:
+ * https://en.wikipedia.org/wiki/Binary_space_partitioning
+ * ftp://ftp.sgi.com/other/bspfaq/faq/bspfaq.html
+ */
 class BSPTree {
 public:
   /**
@@ -92,7 +98,9 @@ public:
     BuildTree(mRoot, aLayers);
   }
 
-  // Builds and returns the back-to-front draw order for the created BSP tree.
+  /**
+   * Builds and returns the back-to-front draw order for the created BSP tree.
+   */
   nsTArray<LayerPolygon> GetDrawOrder() const
   {
     nsTArray<LayerPolygon> layers;
@@ -104,8 +112,10 @@ private:
   BSPTreeArena mPool;
   BSPTreeNode* mRoot;
 
-  // BuildDrawOrder and BuildTree are called recursively. The depth of the
-  // recursion depends on the amount of polygons and their intersections.
+  /**
+   * BuildDrawOrder and BuildTree are called recursively. The depth of the
+   * recursion depends on the amount of polygons and their intersections.
+   */
   void BuildDrawOrder(BSPTreeNode* aNode,
                       nsTArray<LayerPolygon>& aLayers) const;