Add documentation (#35)

* Add documentation

* Lint

* add docs-coverage rule

* docs: complete documentation coverage to 100% for types

* Add operator documentation

* Lint

* feat(docs): Add local documentation targets to Makefile

* conductor(checkpoint): Checkpoint end of Phase 1

* feat(docs): Add docs-check-coverage target to Makefile

* feat(docs): Add docs-check-links target to Makefile

* conductor(checkpoint): Checkpoint end of Phase 2

* feat(docs): Add Documentation CI/CD workflow

* conductor(checkpoint): Checkpoint end of Phase 3

* build: include swift-docc-plugin only on macOS to fix Windows CI

Author: ctreffs

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ master, main ]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-docs:
+    name: Build Documentation
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Swift
+        uses: swift-actions/setup-swift@v2
+        with:
+          swift-version: "6.1"
+
+      - name: Build Documentation
+        run: make docs-generate
+
+      - name: Check Documentation Quality
+        run: |
+          make docs-check-coverage
+          make docs-check-links
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .build/documentation
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build-docs
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Makefile

@@ -2,15 +2,39 @@ UNAME_S := $(shell uname -s)
 SWIFT_FLAGS ?= --disable-sandbox
 PACKAGE_SWIFT_VERSION := $(shell grep "swift-tools-version" Package.swift | head -n 1 | cut -d ":" -f 2 | xargs)
 
+HOSTING_BASE_PATH ?= fireblade-math
+
 # Targets
-.PHONY: setup lint lint-fix test test-coverage clean pre-commit
+.PHONY: setup lint lint-fix test test-coverage clean pre-commit docs docs-preview docs-generate docs-coverage
 
 setup:
 	@echo "Detected Package Swift Version: $(PACKAGE_SWIFT_VERSION)"
 	@which mint > /dev/null || (echo "Mint not found. Installing via Homebrew..." && brew install mint)
 	mint bootstrap
 	swift package resolve $(SWIFT_FLAGS)
 
+docs: docs-generate
+
+docs-preview:
+	swift package --disable-sandbox preview-documentation --target FirebladeMath
+
+docs-generate:
+	swift package --disable-sandbox \
+		--allow-writing-to-directory .build/documentation \
+		generate-documentation --target FirebladeMath \
+		--disable-indexing \
+		--transform-for-static-hosting \
+		--hosting-base-path $(HOSTING_BASE_PATH) \
+		--output-path .build/documentation
+
+docs-coverage: docs-check-coverage
+
+docs-check-coverage:
+	swift package --disable-sandbox generate-documentation --target FirebladeMath --experimental-documentation-coverage --coverage-summary-level brief
+
+docs-check-links:
+	swift package --disable-sandbox generate-documentation --target FirebladeMath --analyze --warnings-as-errors
+
 lint:
 	mint run swiftlint lint --quiet
 	mint run swiftformat --lint --swiftversion $(PACKAGE_SWIFT_VERSION) Sources/ Tests/

Package.resolved

@@ -25,6 +25,8 @@ let package = Package(
         .trait(name: "simd"),
         .trait(name: "default", enabledTraits: Set(defaultTraits))
     ],
+    dependencies: [
+    ],
     targets: [
         .target(
             name: "FirebladeMath",
@@ -36,3 +38,9 @@ let package = Package(
             swiftSettings: swiftSettings)
     ]
 )
+
+#if os(macOS)
+package.dependencies.append(
+    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.6")
+)
+#endif

Package.swift

@@ -1,13 +1,21 @@
+/// Factor to convert degrees to radians (Double).
 public let kDegreeToRadians64 = Double.pi / 180.0
+/// Factor to convert degrees to radians (Float).
 public let kDegreeToRadians32 = Float(kDegreeToRadians64)
 
+/// Factor to convert radians to degrees (Double).
 public let kRadiansToDegree64: Double = 180.0 / Double.pi
+/// Factor to convert radians to degrees (Float).
 public let kRadiansToDegree32 = Float(kRadiansToDegree64)
 
+/// Extension to add constants to Float.
 extension Float {
+    /// Half of Pi (π/2).
     public static let halfPi = Float(Double.halfPi)
 }
 
+/// Extension to add constants to Double.
 extension Double {
+    /// Half of Pi (π/2).
     public static let halfPi: Double = .pi * 0.5
 }

Sources/FirebladeMath/Constants.swift

@@ -6,24 +6,24 @@ import Darwin
 import Glibc
 #endif
 
-/// Computes the absolute value of a floating point value arg.
+/// Computes the absolute value of a floating point value x.
 ///
-/// - Parameter float:     floating point value
-/// - Returns: If successful, returns the absolute value of arg (|arg|). The value returned is exact and does not depend on any rounding modes.
-public func abs(_ float: Float) -> Float {
-    fabsf(float)
+/// - Parameter x: floating point value
+/// - Returns: If successful, returns the absolute value of x (|x|). The value returned is exact and does not depend on any rounding modes.
+public func abs(_ x: Float) -> Float {
+    fabsf(x)
 }
 
-/// Computes the absolute value of a floating point value arg.
+/// Computes the absolute value of a floating point value x.
 ///
-/// - Parameter double:     floating point value
-/// - Returns: If successful, returns the absolute value of arg (|arg|). The value returned is exact and does not depend on any rounding modes.
-public func abs(_ double: Double) -> Double {
+/// - Parameter x: floating point value
+/// - Returns: If successful, returns the absolute value of x (|x|). The value returned is exact and does not depend on any rounding modes.
+public func abs(_ x: Double) -> Double {
     #if canImport(Darwin)
-    return Darwin.fabs(double)
+    return Darwin.fabs(x)
     #elseif canImport(Glibc)
-    return Glibc.fabs(double)
+    return Glibc.fabs(x)
     #else
-    return Foundation.fabs(double)
+    return Foundation.fabs(x)
     #endif
 }

Sources/FirebladeMath/Functions/abs.swift

@@ -6,34 +6,34 @@ import Darwin
 import Glibc
 #endif
 
-/// Computes the principal value of the arc cosine of arg.
+/// Computes the principal value of the arc cosine of x.
 ///
-/// - Parameter float: floating point value
-/// - Returns: If no errors occur, the arc cosine of arg (arccos(arg)) in the range [0 ; π], is returned.
+/// - Parameter x: floating point value
+/// - Returns: If no errors occur, the arc cosine of x (arccos(x)) in the range [0 ; π], is returned.
 ///               If a domain error occurs, an implementation-defined value is returned (NaN where supported).
 ///                If a range error occurs due to underflow, the correct result (after rounding) is returned.
-public func acos(_ float: Float) -> Float {
+public func acos(_ x: Float) -> Float {
     #if canImport(Darwin)
-    return Darwin.acosf(float)
+    return Darwin.acosf(x)
     #elseif canImport(Glibc)
-    return Glibc.acosf(float)
+    return Glibc.acosf(x)
     #else
-    return Foundation.acosf(float)
+    return Foundation.acosf(x)
     #endif
 }
 
-/// Computes the principal value of the arc cosine of arg.
+/// Computes the principal value of the arc cosine of x.
 ///
-/// - Parameter double: floating point value
-/// - Returns: If no errors occur, the arc cosine of arg (arccos(arg)) in the range [0 ; π], is returned.
+/// - Parameter x: floating point value
+/// - Returns: If no errors occur, the arc cosine of x (arccos(x)) in the range [0 ; π], is returned.
 ///               If a domain error occurs, an implementation-defined value is returned (NaN where supported).
 ///                If a range error occurs due to underflow, the correct result (after rounding) is returned.
-public func acos(_ double: Double) -> Double {
+public func acos(_ x: Double) -> Double {
     #if canImport(Darwin)
-    return Darwin.acos(double)
+    return Darwin.acos(x)
     #elseif canImport(Glibc)
-    return Glibc.acos(double)
+    return Glibc.acos(x)
     #else
-    return Foundation.acos(double)
+    return Foundation.acos(x)
     #endif
 }

Sources/FirebladeMath/Functions/acos.swift

@@ -6,34 +6,34 @@ import Darwin
 import Glibc
 #endif
 
-///  Computes the inverse hyperbolic cosine of arg.
+///  Computes the inverse hyperbolic cosine of x.
 ///
-/// - Parameter double:     floating point value representing the area of a hyperbolic sector
-/// - Returns: If no errors occur, the inverse hyperbolic cosine of arg (cosh-1
-///    (arg), or arcosh(arg)) on the interval [0, +∞], is returned.
+/// - Parameter x: floating point value representing the area of a hyperbolic sector
+/// - Returns: If no errors occur, the inverse hyperbolic cosine of x (cosh-1
+///    (x), or arcosh(x)) on the interval [0, +∞], is returned.
 /// If a domain error occurs, an implementation-defined value is returned (NaN where supported).
-public func acosh(_ double: Double) -> Double {
+public func acosh(_ x: Double) -> Double {
     #if canImport(Darwin)
-    return Darwin.acosh(double)
+    return Darwin.acosh(x)
     #elseif canImport(Glibc)
-    return Glibc.acosh(double)
+    return Glibc.acosh(x)
     #else
-    return Foundation.acosh(double)
+    return Foundation.acosh(x)
     #endif
 }
 
-///  Computes the inverse hyperbolic cosine of arg.
+///  Computes the inverse hyperbolic cosine of x.
 ///
-/// - Parameter float:     floating point value representing the area of a hyperbolic sector
-/// - Returns: If no errors occur, the inverse hyperbolic cosine of arg (cosh-1
-///    (arg), or arcosh(arg)) on the interval [0, +∞], is returned.
+/// - Parameter x: floating point value representing the area of a hyperbolic sector
+/// - Returns: If no errors occur, the inverse hyperbolic cosine of x (cosh-1
+///    (x), or arcosh(x)) on the interval [0, +∞], is returned.
 /// If a domain error occurs, an implementation-defined value is returned (NaN where supported).
-public func acosh(_ float: Float) -> Float {
+public func acosh(_ x: Float) -> Float {
     #if canImport(Darwin)
-    return Darwin.acoshf(float)
+    return Darwin.acoshf(x)
     #elseif canImport(Glibc)
-    return Glibc.acoshf(float)
+    return Glibc.acoshf(x)
     #else
-    return Foundation.acoshf(float)
+    return Foundation.acoshf(x)
     #endif
 }

Sources/FirebladeMath/Functions/acosh.swift

@@ -1,3 +1,6 @@
+/// Computes the adjugate of a 3x3 matrix.
+/// - Parameter inMat: The input matrix.
+/// - Returns: The adjugate of the input matrix.
 public func adjugate(_ inMat: Mat3x3f) -> Mat3x3f {
     var out = Mat3x3f.identity
 
@@ -16,6 +19,9 @@ public func adjugate(_ inMat: Mat3x3f) -> Mat3x3f {
     return out
 }
 
+/// Computes the adjugate of a 3x3 matrix.
+/// - Parameter inMat: The input matrix.
+/// - Returns: The adjugate of the input matrix.
 public func adjugate(_ inMat: Mat3x3d) -> Mat3x3d {
     var out = Mat3x3d.identity
 
@@ -34,6 +40,9 @@ public func adjugate(_ inMat: Mat3x3d) -> Mat3x3d {
     return out
 }
 
+/// Computes the adjugate of a 4x4 matrix.
+/// - Parameter m: The input matrix.
+/// - Returns: The adjugate of the input matrix.
 public func adjugate(_ m: Mat4x4f) -> Mat4x4f {
     // Adjugate is the transpose of the cofactor matrix.
     // cofactor(i, j) = (-1)^(i+j) * minor(i, j)
@@ -63,6 +72,9 @@ public func adjugate(_ m: Mat4x4f) -> Mat4x4f {
     return res
 }
 
+/// Computes the adjugate of a 4x4 matrix.
+/// - Parameter m: The input matrix.
+/// - Returns: The adjugate of the input matrix.
 public func adjugate(_ m: Mat4x4d) -> Mat4x4d {
     var res = Mat4x4d.identity
 

Sources/FirebladeMath/Functions/adjugate.swift

@@ -3,6 +3,8 @@ import func simd.simd_angle
 #endif
 
 /// Returns the angle by which a quaternion rotates.
+/// - Parameter quat: The quaternion.
+/// - Returns: The angle in radians.
 public func angle(_ quat: Quat4f) -> Float {
     #if FRB_MATH_USE_SIMD
     return simd.simd_angle(quat.storage)
@@ -13,6 +15,8 @@ public func angle(_ quat: Quat4f) -> Float {
 }
 
 /// Returns the angle by which a quaternion rotates.
+/// - Parameter quat: The quaternion.
+/// - Returns: The angle in radians.
 public func angle(_ quat: Quat4d) -> Double {
     #if FRB_MATH_USE_SIMD
     return simd.simd_angle(quat.storage)