Add code comments justifying use of specialized methods (#89)

* Add why-special note for BezierCurve

* Add why-special notes for conics

* Add why-special notes for geometries with infinite extent

* Add why-special notes for Ring and Rope

* Add why-special notes for simplex types

src/specializations/BezierCurve.jl

@@ -1,5 +1,12 @@
 ################################################################################
 #                   Specialized Methods for BezierCurve
+#
+# Why Specialized?
+#   The parametric function in Meshes.jl for BezierCurve accepts an argument
+#   of type Meshes.BezierEvalMethod, in which the method for generating
+#   parametric points along the curve is specified. These specialized methods
+#   are essentially identical to the generic ones, except that they provide a
+#   keyword argument and pass through the specified algorithm choice.
 ################################################################################
 
 function lineintegral(

src/specializations/ConeSurface.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                      Specialized Methods for ConeSurface
+#
+# Why Specialized?
+#   The parametric function that Meshes.jl currently implements for ConeSurface
+#   only parameterizes the rounded walls of the cone, but this Geometry surface is
+#   defined as including the circular base surface as well. These methods simply
+#   integrate both the base and walls and return the sum of the two integrals.
 ################################################################################
 
 function integral(

src/specializations/CylinderSurface.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                  Specialized Methods for CylinderSurface
+#
+# Why Specialized?
+#   The parametric function that Meshes.jl currently implements for CylinderSurface
+#   only parameterizes the rounded walls, but this Geometry surface is defined as
+#   including the top and bottom circular base surfaces as well. These methods
+#   simply integrate the base and walls and return the sum of the three integrals.
 ################################################################################
 
 function integral(

src/specializations/FrustumSurface.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                   Specialized Methods for FrustumSurface
+#
+# Why Specialized?
+#   The parametric function that Meshes.jl currently implements for FrustumSurface
+#   only parameterizes the rounded walls, but this Geometry surface is defined as
+#   including the truncated top and bottom surfaces as well. These methods simply
+#   integrate both the walls and the ends and return the sum of the these integrals.
 ################################################################################
 
 function integral(

src/specializations/Line.jl

@@ -1,5 +1,10 @@
 ################################################################################
 #                   Specialized Methods for Line
+#
+# Why Specialized?
+#   The Line geometry is a special case, representing a line of infinite length
+#   that passes through two points. This requires another domain transformation
+#   mapping from the typical parametric region [0,1] to an infinite one (-∞,∞).
 ################################################################################
 
 function integral(

src/specializations/Plane.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                      Specialized Methods for Plane
+#
+# Why Specialized?
+#   The Plane geometry is a special case, representing a planar surface with
+#   infinite extent along two basis vectors. This requires a pair of domain
+#   transformations mapping from the typical parametric region [0,1]² to an
+#   infinite one (-∞,∞)².
 ################################################################################
 
 function integral(

src/specializations/Ray.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                   Specialized Methods for Ray
+#
+# Why Specialized?
+#   The Ray geometry is a special case, representing a ray, originating at a point
+#   and extending an infinite length in a particular direction. This requires
+#   a domain transformation mapping from the typical parametric region [0,1] to
+#   an infinite one (-∞,∞).
 ################################################################################
 
 function integral(

src/specializations/Ring.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                      Specialized Methods for Ring
+#
+# Why Specialized?
+#   The Ring geometry defines a polytope whose length spans segments between
+#   consecutive points that form a closed path. Meshes.jl does not define a
+#   parametric function for Ring's, but they can be decomposed into their
+#   constituent Segment's, integrated separately, and then summed.
 ################################################################################
 
 function integral(

src/specializations/Rope.jl

@@ -1,5 +1,11 @@
 ################################################################################
 #                      Specialized Methods for Rope
+#
+# Why Specialized?
+#   The Rope geometry defines a polytope whose length spans segments between
+#   consecutive points. Meshes.jl does not define a parametric function for
+#   Rope's, but they can be decomposed into their constituent Segment's,
+#   integrated separately, and then summed.
 ################################################################################
 
 function integral(

src/specializations/Tetrahedron.jl

@@ -1,5 +1,12 @@
 ################################################################################
 #                  Specialized Methods for Tetrahedron
+#
+# Why Specialized?
+#   The Tetrahedron geometry is a volumetric simplex whose parametric function
+#   in Meshes.jl uses barycentric coordinates on a domain {u,v,w} with coordinates
+#   that are non-negative and bound by the surface $u + v + w ≤ 1$. This requires
+#   a multi-step domain transformation whose derivation is detailed in the package
+#   documentation.
 ################################################################################
 
 function integral(

src/specializations/Triangle.jl

@@ -1,5 +1,12 @@
 ################################################################################
 #                    Specialized Methods for Triangle
+#
+# Why Specialized?
+#   The Triangle geometry is a surface simplex whose parametric function in
+#   Meshes.jl uses barycentric coordinates on a domain {u,v} with coordinates
+#   that are non-negative and bound by the surface $u + v ≤ 1$. This requires a
+#   multi-step domain transformation whose derivation is detailed in the package
+#   documentation.
 ################################################################################
 
 """