fix: Fix some doxygen docs errors (#2130)

.github/workflows/docs.yml

@@ -5,23 +5,14 @@ on:
     branches: [develop]
   workflow_dispatch:
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 concurrency:
   # Only cancel in-progress jobs or runs for the current workflow - matches against branch & tags
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  build:
     runs-on: ubuntu-latest
-    continue-on-error: true
     container:
       image: ghcr.io/xrplf/clio-ci:latest
 
@@ -31,10 +22,16 @@ jobs:
         with:
           lfs: true
 
-      - name: Build docs
-        run: |
-          mkdir -p build_docs && cd build_docs
-          cmake ../docs && cmake --build . --target docs
+      - name: Create build directory
+        run: mkdir build_docs
+
+      - name: Configure CMake
+        working-directory: build_docs
+        run: cmake ../docs
+
+      - name: Build
+        working-directory: build_docs
+        run: cmake --build . --target docs
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -45,6 +42,19 @@ jobs:
           path: build_docs/html
           name: docs-develop
 
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -11,6 +11,8 @@
 #
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+exclude: ^docs/doxygen-awesome-theme/
+
 repos:
   # `pre-commit sample-config` default hooks
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -20,16 +22,13 @@ repos:
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
       - id: end-of-file-fixer
-        exclude: ^docs/doxygen-awesome-theme/
       - id: trailing-whitespace
-        exclude: ^docs/doxygen-awesome-theme/
 
   # Autoformat: YAML, JSON, Markdown, etc.
   - repo: https://github.com/rbubley/mirrors-prettier
     rev: 787fb9f542b140ba0b2aced38e6a3e68021647a3 # frozen: v3.5.3
     hooks:
       - id: prettier
-        exclude: ^docs/doxygen-awesome-theme/
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: 586c3ea3f51230da42bab657c6a32e9e66c364f0 # frozen: v0.44.0

docs/Doxyfile

@@ -22,6 +22,7 @@ WARNINGS               = ${LINT}
 WARN_NO_PARAMDOC       = ${LINT}
 WARN_IF_INCOMPLETE_DOC = ${LINT}
 WARN_IF_UNDOCUMENTED   = ${LINT}
+WARN_AS_ERROR          = ${WARN_AS_ERROR}
 
 GENERATE_LATEX         = NO
 GENERATE_HTML          = YES

pre-commit-hooks/check-doxygen-docs.sh

@@ -61,6 +61,7 @@ pushd ${DOCDIR} > /dev/null 2>&1
 cat ${ROOT}/docs/Doxyfile | \
 sed \
     -e "s/\${LINT}/YES/" \
+    -e "s/\${WARN_AS_ERROR}/NO/" \
     -e "s!\${SOURCE}!${ROOT}!" \
     -e "s/\${USE_DOT}/NO/" \
     -e "s/\${EXCLUDES}/impl/" \

src/etl/impl/SourceImpl.hpp

@@ -198,7 +198,6 @@ public:
      *
      * @param sequence Sequence of the ledger to download
      * @param numMarkers Number of markers to generate for async calls
-     * @param cacheOnly Only insert into cache, not the DB; defaults to false
      * @return A std::pair of the data and a bool indicating whether the download was successful
      */
     std::pair<std::vector<std::string>, bool>

src/web/ng/impl/ErrorHandling.hpp

@@ -93,7 +93,7 @@ public:
     makeJsonParsingError() const;
 
     /**
-     * @beirf Compose an error into json object from a status.
+     * @brief Compose an error into json object from a status.
      *
      * @param error The status to compose into a json object.
      * @return The composed json object.