Update docstrings for consistency and clarity, associated style improvements

Author: mikeingold

src/integral_aliases.jl

@@ -9,6 +9,9 @@ Numerically integrate a given function `f(::Point)` along a line-like `geometry`
 using a particular numerical integration `rule` with floating point precision of
 type `FP`.
 
+This is a convenience wrapper around [`integral`](@ref) that additionally enforces
+a requirement that the geometry have one parametric dimension.
+
 Rule types available:
 - [`GaussKronrod`](@ref) (default)
 - [`GaussLegendre`](@ref)
@@ -20,14 +23,12 @@ function lineintegral(
         rule::IntegrationRule = GaussKronrod();
         kwargs...
 )
-    N = Meshes.paramdim(geometry)
-
-    if N == 1
-        return integral(f, geometry, rule; kwargs...)
-    else
+    if (N = Meshes.paramdim(geometry)) != 1
         throw(ArgumentError("Performing a line integral on a geometry \
                             with $N parametric dimensions not supported."))
     end
+
+    return integral(f, geometry, rule; kwargs...)
 end
 
 ################################################################################
@@ -41,6 +42,9 @@ Numerically integrate a given function `f(::Point)` along a surface `geometry`
 using a particular numerical integration `rule` with floating point precision of
 type `FP`.
 
+This is a convenience wrapper around [`integral`](@ref) that additionally enforces
+a requirement that the geometry have two parametric dimensions.
+
 Algorithm types available:
 - [`GaussKronrod`](@ref)
 - [`GaussLegendre`](@ref)
@@ -52,14 +56,12 @@ function surfaceintegral(
         rule::IntegrationRule = HAdaptiveCubature();
         kwargs...
 )
-    N = Meshes.paramdim(geometry)
-
-    if N == 2
-        return integral(f, geometry, rule; kwargs...)
-    else
+    if (N = Meshes.paramdim(geometry)) != 2
         throw(ArgumentError("Performing a surface integral on a geometry \
                             with $N parametric dimensions not supported."))
     end
+
+    return integral(f, geometry, rule; kwargs...)
 end
 
 ################################################################################
@@ -73,6 +75,9 @@ Numerically integrate a given function `f(::Point)` throughout a volumetric
 `geometry` using a particular numerical integration `rule` with floating point
 precision of type `FP`.
 
+This is a convenience wrapper around [`integral`](@ref) that additionally enforces
+a requirement that the geometry have three parametric dimensions.
+
 Algorithm types available:
 - [`GaussKronrod`](@ref)
 - [`GaussLegendre`](@ref)
@@ -84,12 +89,10 @@ function volumeintegral(
         rule::IntegrationRule = HAdaptiveCubature();
         kwargs...
 )
-    N = Meshes.paramdim(geometry)
-
-    if N == 3
-        return integral(f, geometry, rule; kwargs...)
-    else
+    if (N = Meshes.paramdim(geometry)) != 3
         throw(ArgumentError("Performing a volume integral on a geometry \
                             with $N parametric dimensions not supported."))
     end
+
+    return integral(f, geometry, rule; kwargs...)
 end

src/specializations/BezierCurve.jl

@@ -13,20 +13,11 @@
 #                              integral
 ################################################################################
 """
-    integral(f, curve::BezierCurve, rule = GaussKronrod();
-             diff_method=Analytical(), FP=Float64, alg=Meshes.Horner())
+    integral(f, curve::BezierCurve[, rule = GaussKronrod()]; kwargs...)
 
 Like [`integral`](@ref) but integrates along the domain defined by `curve`.
 
-# Arguments
-- `f`: an integrand function, i.e. any callable with a method `f(::Meshes.Point)`
-- `curve`: a `Meshes.BezierCurve` that defines the integration domain
-- `rule = GaussKronrod()`: optionally, the `IntegrationRule` used for integration
-
-# Keyword Arguments
-- `diff_method::DifferentiationMethod = Analytical()`: the method to use for
-calculating Jacobians that are used to calculate differential elements
-- `FP = Float64`: the floating point precision desired
+# Special Keyword Arguments
 - `alg = Meshes.Horner()`:  the method to use for parametrizing `curve`. Alternatively,
 `alg=Meshes.DeCasteljau()` can be specified for increased accuracy, but comes with a
 steep performance cost, especially for curves with a large number of control points.

src/specializations/PolyArea.jl

@@ -9,7 +9,7 @@
 ################################################################################
 
 """
-    integral(f, area::PolyArea, rule = HAdaptiveCubature(); kwargs...)
+    integral(f, area::PolyArea[, rule = HAdaptiveCubature()]; kwargs...)
 
 Like [`integral`](@ref) but integrates over the surface domain defined by a `PolyArea`.
 The surface is first discretized into facets that are integrated independently using

src/specializations/Ring.jl

@@ -9,22 +9,11 @@
 ################################################################################
 
 """
-    integral(f, ring::Ring, rule = GaussKronrod();
-             diff_method=FiniteDifference(), FP=Float64)
+    integral(f, ring::Ring[, rule = GaussKronrod()]; kwargs...)
 
 Like [`integral`](@ref) but integrates along the domain defined by `ring`. The
 specified integration `rule` is applied independently to each segment formed by
 consecutive points in the Ring.
-
-# Arguments
-- `f`: an integrand function, i.e. any callable with a method `f(::Meshes.Point)`
-- `ring`: a `Ring` that defines the integration domain
-- `rule = GaussKronrod()`: optionally, the `IntegrationRule` used for integration
-
-# Keyword Arguments
-- `diff_method::DifferentiationMethod = FiniteDifference()`: the method to use for
-calculating Jacobians that are used to calculate differential elements
-- `FP = Float64`: the floating point precision desired
 """
 function integral(
         f,

src/specializations/Rope.jl

@@ -9,22 +9,11 @@
 ################################################################################
 
 """
-    integral(f, rope::Rope, rule = GaussKronrod();
-             diff_method=FiniteDifference(), FP=Float64)
+    integral(f, rope::Rope[, rule = GaussKronrod()]; kwargs...)
 
 Like [`integral`](@ref) but integrates along the domain defined by `rope`. The
 specified integration `rule` is applied independently to each segment formed by
 consecutive points in the Rope.
-
-# Arguments
-- `f`: an integrand function, i.e. any callable with a method `f(::Meshes.Point)`
-- `rope`: a `Rope` that defines the integration domain
-- `rule = GaussKronrod()`: optionally, the `IntegrationRule` used for integration
-
-# Keyword Arguments
-- `diff_method::DifferentiationMethod = FiniteDifference()`: the method to use for
-calculating Jacobians that are used to calculate differential elements
-- `FP = Float64`: the floating point precision desired
 """
 function integral(
         f,