More consistently use math-formatted arguments in doc strings.

Also fixes a couple of copy-paste errors in describing the return values of some private functions. This change is enabled by updating to MathJax ≥v3.2.0 which correctly handles rendering inline Unicode math characters as math. (Previously they instead appeared as upright text-mode characters.)
jmert · Jan 3, 2022 · 8a66b03 · 8a66b03
1 parent 62e2396
commit 8a66b03
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 31 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,7 +8,13 @@ doctest = "--fix"  in ARGS ? :fix :
 DocMeta.setdocmeta!(CMB, :DocTestSetup, :(using CMB); recursive=true)
 
 makedocs(
-    format = Documenter.HTML(mathengine = Documenter.MathJax3()),
+    format = Documenter.HTML(
+            mathengine = Documenter.MathJax3(
+                    # If and/or when Documenter is updated to do use MathJax ≥v3.2.0,
+                    # this line can be deleted. (See Documenter.jl#174)
+                    url = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-svg.js"
+            )
+    ),
     sitename = "CMB Analysis",
     authors = "Justin Willmert",
     modules = [CMB],

diff --git a/src/healpix.jl b/src/healpix.jl
@@ -291,8 +291,8 @@ pix2ringidx(nside, p) = pix2ringidx(promote(nside, p)...)
 """
     z = pix2z(nside, p)
 
-Computes the cosine of the colatitude `z` for the given pixel `p`, where `nside` is the
-Nside resolution factor.
+Computes the cosine of the colatitude ``z = \\cos(θ)`` for the given pixel `p`, where
+`nside` is the Nside resolution factor.
 """
 function pix2z(nside::I, p::I) where I<:Integer
     checkhealpix(nside, p)
@@ -301,7 +301,7 @@ end
 pix2z(nside, p) = pix2z(promote(nside, p)...)
 
 """
-    (θ,ϕ) = unsafe_pix2z(nside, p)
+    z = unsafe_pix2z(nside, p)
 
 Like [`pix2z`](@ref) but does not call [`checkhealpix`](@ref) to check `nside` and pixel
 index validity.
@@ -345,13 +345,13 @@ end
 """
     θ = pix2theta(nside, p)
 
-Computes the colatitude `θ` for the given pixel `p`, where `nside` is the Nside resolution
+Computes the colatitude ``θ`` for the given pixel `p`, where `nside` is the Nside resolution
 factor.
 """
 pix2theta(nside, p) = acos(pix2z(promote(nside, p)...))
 
 """
-    (θ,ϕ) = unsafe_pix2theta(nside, p)
+    θ = unsafe_pix2theta(nside, p)
 
 Like [`pix2theta`](@ref) but does not call [`checkhealpix`](@ref) to check `nside` and pixel
 index validity.
@@ -361,7 +361,7 @@ unsafe_pix2theta(nside, p) = acos(unsafe_pix2z(promote(nside, p)...))
 """
     ϕ = pix2phi(nside, p)
 
-Computes the azimuth `ϕ` for the given pixel `p`, where `nside` is the Nside resolution
+Computes the azimuth ``ϕ`` for the given pixel `p`, where `nside` is the Nside resolution
 factor.
 """
 function pix2phi(nside::I, p::I) where I<:Integer
@@ -371,7 +371,7 @@ end
 pix2phi(nside, p) = pix2phi(promote(nside, p)...)
 
 """
-    (θ,ϕ) = unsafe_pix2phi(nside, p)
+    ϕ = unsafe_pix2phi(nside, p)
 
 Like [`pix2phi`](@ref) but does not call [`checkhealpix`](@ref) to check `nside` and pixel
 index validity.
@@ -409,7 +409,7 @@ end
 """
     (θ,ϕ) = pix2ang(nside, p)
 
-Computes the colatitude and azimuth pair `(θ,ϕ)` for the given pixel `p`, where
+Computes the colatitude and azimuth pair ``(θ,ϕ)`` for the given pixel `p`, where
 `nside` is the Nside resolution factor.
 """
 function pix2ang(nside::I, p::I) where {I<:Integer}
@@ -433,7 +433,7 @@ end
 """
     r = pix2vec(nside, p)
 
-Computes the unit vector `r` pointing to the pixel center of the given pixel `p`, where
+Computes the unit vector ``r`` pointing to the pixel center of the given pixel `p`, where
 `nside` is the Nside resolution factor.
 """
 function pix2vec(nside::I, p::I) where I<:Integer
@@ -443,7 +443,7 @@ end
 pix2vec(nside, p) = pix2vec(promote(nside, p)...)
 
 """
-    (θ,ϕ) = unsafe_pix2vec(nside, p)
+    r = unsafe_pix2vec(nside, p)
 
 Like [`pix2vec`](@ref) but does not call [`checkhealpix`](@ref) to check `nside` and pixel
 index validity.
@@ -465,7 +465,7 @@ end
     p = ang2pix(nside, θ, ϕ)
 
 Computes the HEALPix pixel index `p` which contains the point ``(θ,ϕ)`` given by the
-colatitude `θ` and azimuth `ϕ`, where `nside` is the Nside resolution factor.
+colatitude ``θ`` and azimuth ``ϕ``, where `nside` is the Nside resolution factor.
 """
 function ang2pix(nside::Integer, θ::F, ϕ::F) where {F}
     checkhealpix(nside)
@@ -479,7 +479,7 @@ ang2pix(nside::Integer, θ, ϕ) = ang2pix(nside, promote(θ, ϕ)...)
     p = vec2pix(nside, r)
 
 Computes the HEALPix pixel index `p` which contains the point at the end of the unit
-vector `r`, where `nside` is the Nside resolution factor.
+vector ``r``, where `nside` is the Nside resolution factor.
 """
 function vec2pix(nside::Integer, r)
     checkhealpix(nside)
@@ -491,7 +491,7 @@ end
     p = unsafe_ang2pix(nside, θ, ϕ)
 
 Like [`ang2pix`](@ref) but neither calls [`checkhealpix`](@ref) to check the validity of
-`nside` nor checks the domain of the spherical coordinates `θ` and `ϕ`.
+`nside` nor checks the domain of the spherical coordinates ``θ`` and ``ϕ``.
 """
 function unsafe_ang2pix(nside::Integer, θ, ϕ)
     z = cos(θ)
@@ -501,7 +501,7 @@ end
 """
     p = unsafe_vec2pix(nside, r)
 
-Like [`vec2pix`](@ref) but does not check the validity of the `nside` or length of `r`.
+Like [`vec2pix`](@ref) but does not check the validity of the `nside` or length of ``r``.
 """
 @propagate_inbounds function unsafe_vec2pix(nside::Integer, r)
     z = r[3]
@@ -513,7 +513,8 @@ end
 """
     p = unsafe_zphi2pix(nside, z, ϕ)
 
-Like [`unsafe_ang2pix`](@ref) but uses the value ``z = \\cos(θ)`` instead.
+Like [`unsafe_ang2pix`](@ref) but takes the value ``z = \\cos(θ)`` instead of the colatitude
+``θ``.
 """
 function unsafe_zphi2pix(nside::I, z::F, ϕ::F) where {I<:Integer, F}
     z′ = abs(z)

diff --git a/src/sphere.jl b/src/sphere.jl
@@ -44,7 +44,7 @@ const ẑ = SVector(0, 0, 1)
     r = cartvec(θ, ϕ)
     r = cartvec((θ, ϕ))
 
-Converts the colatitude-azimuth pair `(θ, ϕ)` to a Cartesian unit vector `r`.
+Converts the colatitude-azimuth pair ``(θ, ϕ)`` to a Cartesian unit vector ``r``.
 """
 function cartvec(θ, ϕ)
     sθ, cθ = sincos(float(θ))
@@ -56,7 +56,7 @@ end
 """
     θ, ϕ = colataz(r)
 
-Converts the Cartesian unit vector `r` to a colatitude-azimuth pair `(θ, ϕ)` in radians.
+Converts the Cartesian unit vector ``r`` to a colatitude-azimuth pair ``(θ, ϕ)`` in radians.
 """
 function colataz(r::SVector{3})
     θ = acos(r[3])
@@ -68,8 +68,8 @@ end
     θ, ϕ = colataz(δ, λ)
     θ, ϕ = colataz((δ, λ))
 
-Converts the latitude-longitude pair `(δ, λ)` in degrees to colatitude-azimuth `(θ, ϕ)` in
-radians.
+Converts the latitude-longitude pair ``(δ, λ)`` in degrees to colatitude-azimuth ``(θ, ϕ)``
+in radians.
 """
 function colataz(δ, λ)
     θ, ϕ = unsafe_colataz(δ, λ)
@@ -88,7 +88,7 @@ end
 """
     δ, λ = latlon(r)
 
-Converts the Cartesian unit vector `r` to a latitude-longitude pair `(δ, λ)` in degrees.
+Converts the Cartesian unit vector ``r`` to a latitude-longitude pair ``(δ, λ)`` in degrees.
 """
 function latlon(r::SVector{3})
     δ = asind(r[3])
@@ -100,8 +100,8 @@ end
     δ, λ = latlon(θ, ϕ)
     δ, λ = latlon((θ, ϕ))
 
-Converts the colatitude-azimuth pair `(θ, ϕ)` in radians to latitude-longitude `(δ, λ)` in
-radians.
+Converts the colatitude-azimuth pair ``(θ, ϕ)`` in radians to latitude-longitude ``(δ, λ)``
+in radians.
 """
 function latlon(θ, ϕ)
     θ′, ϕ′ = promote(float(θ), float(ϕ))
@@ -303,8 +303,8 @@ function cosdistance(r₁::AbstractVector, r₂::AbstractVector)
 end
 
 """
-Calculates a position on the sphere a given [`distance`](@ref) (`σ`, in radians) and
-relative [`bearing`](@ref) angle (`α`, in radians) away from a given point (measuring the
+Calculates a position on the sphere a given [`distance`](@ref) (``σ``, in radians) and
+relative [`bearing`](@ref) angle (``α``, in radians) away from a given point (measuring the
 eastward-of-north orientation of the great circle connecting the source and destination
 points with respect to the merdian passing through the source).
 """
@@ -313,11 +313,11 @@ function reckon end
 """
     r′ = reckon(r::AbstractVector, σ, α)
 
-The point on the sphere is given as a unit vector `r`.
+The point on the sphere is given as a unit vector ``r``.
 
 !!! note
-    When `r` points to either the north or south pole, the meridian is defined to be
-    **prime meridian** and the bearing angle `α` is oriented with respect to it.
+    When ``r`` points to either the north or south pole, the meridian is defined to be
+    **prime meridian** and the bearing angle ``α`` is oriented with respect to it.
 
     For example, moving a distance ``π/2`` with no bearing goes to the negative ``x``
     axis (i.e. 0° N, 180° W):
@@ -349,12 +349,12 @@ end
 """
     (θ′, ϕ′) = reckon(θ, ϕ, σ, α)
 
-The point on the sphere is given by the colatitude-azimuth pair (`θ`, `ϕ`), both given
+The point on the sphere is given by the colatitude-azimuth pair ``(θ, ϕ)``, both given
 in radians.
 
 !!! note
-    When `r` points to either the north or south pole, the meridian is defined to be
-    **`θ` meridian**, and the bearing angle `α` is oriented with respect to it.
+    When ``r`` points to either the north or south pole, the meridian is defined to be
+    **``θ`` meridian**, and the bearing angle ``α`` is oriented with respect to it.
 
     For example, moving a distance ``π/2`` with no bearing goes to the equator, with the
     longitude dependent on the input longitude: