Make sure everything is documented from Typedoc's point of view

.github/workflows/ci.yml

@@ -98,7 +98,7 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
 
       - run: npm ci
-      - run: npm run doc
+      - run: npm run doc:typedoc -- --treatWarningsAsErrors
 
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:

assert.js

@@ -8,17 +8,17 @@ import GLib from 'gi://GLib';
 import Gio from 'gi://Gio';
 
 /**
+ * @callback Matcher
  * A function that checks if the actual value meets some condition.
  *
- * @callback Matcher
  * @param {unknown} actual - The actual value to check.
  * @returns {MatchResult} The conclusion of the check.
  */
 
 /**
+ * @typedef MatchResult
  * A result of the check.
  *
- * @typedef MatchResult
  * @property {boolean} ok - Whether the check succeeded.
  * @property {string} [message] - If the check has failed, the description of the failure.
  * @property {unknown} [expected] - Expected value.
@@ -30,6 +30,8 @@ import Gio from 'gi://Gio';
  */
 export class AssertionError extends Error {
     /**
+     * Error name.
+     *
      * @override
      */
     name = 'AssertionError';
@@ -45,11 +47,19 @@ export class AssertionError extends Error {
     constructor(params) {
         super(params.message);
 
-        if ('expected' in params)
+        if ('expected' in params) {
+            /**
+             * Expected value.
+             */
             this.expected = params.expected;
+        }
 
-        if ('actual' in params)
+        if ('actual' in params) {
+            /**
+             * Actual value.
+             */
             this.actual = params.actual;
+        }
     }
 }
 

eslint.config.mjs

@@ -65,6 +65,11 @@ export default defineConfig([
             'tseslint/strictTypeChecked',
             'tseslint/stylisticTypeChecked',
         ],
+        settings: {
+            jsdoc: {
+                overrideReplacesDocs: false,
+            },
+        },
         rules: {
             'max-len': [
                 'error',
@@ -107,6 +112,9 @@ export default defineConfig([
                     FunctionExpression: true,
                     MethodDefinition: true,
                 },
+                contexts: [
+                    'PropertyDefinition[key.type="Identifier"]',
+                ],
             }],
             'jsdoc/require-returns': ['error', {
                 publicOnly: {
@@ -122,6 +130,7 @@ export default defineConfig([
                     'ClassExpression',
                     'FunctionDeclaration',
                     'MethodDefinition[key.type="Identifier"]',
+                    'PropertyDefinition[key.type="Identifier"]',
                 ],
                 exemptedBy: ['inheritdoc', 'ignore', 'private', 'hidden', 'internal'],
             }],
@@ -134,6 +143,20 @@ export default defineConfig([
             'jsdoc/require-description-complete-sentence': 'error',
             'jsdoc/require-hyphen-before-param-description': 'error',
             'jsdoc/require-asterisk-prefix': 'error',
+            'jsdoc/no-restricted-syntax': ['error', {
+                contexts: [
+                    {
+                        comment: 'JsdocBlock[description=/\\S/]:has(JsdocTag[tag=/^(callback|typedef)$/])',
+                        context: 'any',
+                        message: 'Block description before @callback or @typedef is ignored by TypeDoc; put the description after the tag.',
+                    },
+                    {
+                        comment: 'JsdocBlock:not(:has(JsdocTag[tag=/^(inheritdoc|ignore|private|hidden|internal)$/])):has(JsdocTag[tag=/^(callback|typedef)$/]:not([description=/\\S/]))',
+                        context: 'any',
+                        message: '@callback and @typedef must have a description.',
+                    },
+                ],
+            }],
             '@typescript-eslint/only-throw-error': ['error', {
                 allow: [{from: 'package', package: '@girs/glib-2.0', name: 'Error'}],
             }],

reporter.js

@@ -49,9 +49,9 @@ export class Reporter {
 }
 
 /**
+ * @callback Print
  * A function that prints the message somewhere.
  *
- * @callback Print
  * @param {string} message - The message to print.
  */
 

tests/snapshots/tap-report.txt

@@ -7,14 +7,14 @@ not ok 3 - Test suite / failing assertion
       "name": "AssertionError"
     },
     "fileName": "<baseUrl>assert.js",
-    "lineNumber": 46,
+    "lineNumber": 48,
     "columnNumber": 9,
     "message": "Expected true, got false",
     "name": "AssertionError",
     "expected": true,
     "actual": false,
     "toString": "AssertionError: Expected true, got false",
-    "stack": "AssertionError@<baseUrl>assert.js:46:9\nassertThat@<baseUrl>assert.js:67:15\n@<baseUrl>tests/simple.js:50:27\n_init/Gio.Application.prototype.runAsync/</<@<GJS internal>\n"
+    "stack": "AssertionError@<baseUrl>assert.js:48:9\nassertThat@<baseUrl>assert.js:77:15\n@<baseUrl>tests/simple.js:50:27\n_init/Gio.Application.prototype.runAsync/</<@<GJS internal>\n"
   }
   ...
 not ok 4 - Test suite / throws

typedoc.jsonc

@@ -11,5 +11,8 @@
     "plugin": ["typedoc-plugin-mdn-links"],
     "jsDocCompatibility": {
         "exampleTag": false
+    },
+    "validation": {
+        "notDocumented": true
     }
 }