Fix OpenAPI JSDoc annotations and add CI validation

.github/workflows/linux-x64-build-and-test.yml

@@ -154,6 +154,10 @@ jobs:
           fi
           npm run clean
 
+    - name: Validate current JSDoc
+      if: ${{ matrix.ros_distribution == 'lyrical' && matrix['node-version'] == '24.X' }}
+      run: npm run docs
+
     - name: Coveralls
       if: ${{ matrix.ros_distribution == 'lyrical' && matrix['node-version'] == '24.X' }}
       uses: coverallsapp/github-action@v2

lib/openapi.js

@@ -206,7 +206,11 @@ function topLevelSchema(typeName, subType, components) {
  * not the rclnodejs release that generated the document, and there's no
  * source for the former today — so it's a fixed `'0.0.0'` placeholder.
  *
- * @param {{call: object, publish: object, subscribe: object, action?: object}} capabilities
+ * @param {object} capabilities
+ * @param {object} capabilities.call
+ * @param {object} capabilities.publish
+ * @param {object} capabilities.subscribe
+ * @param {object} [capabilities.action]
  * @param {object} [options]
  * @param {string} [options.title]
  * @param {string} [options.basePath] - default '/capability'

tools/jsdoc/README.md

@@ -94,6 +94,15 @@ Because the manifest plus the Git tags fully describe the published set, the
 live site is always reconstructed from a fresh build — nothing can silently
 drop off.
 
+### Pull Request and Push Validation
+
+The [Linux x64 build/test workflow](../../.github/workflows/linux-x64-build-and-test.yml)
+runs `npm run docs` in its Lyrical / Node 24 lane for pull requests and pushes.
+The check builds the current checkout's API docs and landing page using the
+publication template; invalid JSDoc annotations or generation errors fail the job.
+It does not rebuild historical tags, upload artifacts or deploy to Pages.
+The full publication dry run remains necessary to verify all tagged versions.
+
 ### Testing
 
 - Run the workflow manually with `dry_run` enabled first to verify the build