Move jsdoc files to subfolder

jsdoc/jsdoc-synonyms.js

@@ -0,0 +1,17 @@
+/*
+jsdoc-synonyms.js - Add support for @synonym tag
+Copyright (C) 2023 Strudel contributors - see <https://github.com/tidalcycles/strudel/blob/main/packages/midi/midi.mjs>
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+function defineTags(dictionary) {
+  dictionary.defineTag('synonyms', {
+    mustHaveValue: true,
+    onTagged: function (doclet, tag) {
+      doclet.synonyms_text = tag.value;
+      doclet.synonyms = doclet.synonyms_text.split(/[ ,]+/);
+    },
+  });
+}
+
+module.exports = { defineTags: defineTags };

jsdoc/jsdoc.config.json

@@ -0,0 +1,11 @@
+{
+  "source": {
+    "includePattern": ".+\\.(js(doc|x)?|mjs)$",
+    "excludePattern": "node_modules|shift-parser|shift-reducer|shift-traverser|dist"
+  },
+  "plugins": ["plugins/markdown", "jsdoc/jsdoc-synonyms"],
+  "opts": {
+    "destination": "./out/",
+    "recurse": true
+  }
+}

jsdoc/undocumented.mjs

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { parse } from 'acorn';
+import dependencyTree from 'dependency-tree';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getExports(code) {
+  // parse it with acorn
+  let ast;
+  try {
+    ast = parse(code, {
+      ecmaVersion: 11,
+      sourceType: 'module',
+    });
+  } catch (err) {
+    return [`acorn parse error: ${err.name}: ${err.messsage}`];
+  }
+
+  // find all names exported in the file
+  return ast.body
+    .filter((node) => node?.type === 'ExportNamedDeclaration')
+    .map((node) => {
+      const { declaration } = node;
+      if (!declaration) {
+        // e.g. "export { Fraction, controls }"
+        return [];
+      }
+      switch (declaration.type) {
+        case 'VariableDeclaration':
+          return declaration.declarations
+            .map((d) => {
+              switch (d.id.type) {
+                case 'Identifier':
+                  return d.id.name;
+                case 'ObjectPattern':
+                  return d.id.properties.map((p) => p.value.name);
+                default:
+                  return 'unknown declaration: ' + declaration;
+              }
+            })
+            .flat();
+        default:
+          // FunctionDeclaration, ClassDeclaration
+          return declaration.id.name;
+      }
+    })
+    .flat();
+}
+
+function isDocumented(name, docs) {
+  return docs.find(
+    (d) => d.name === name || d.tags?.find((t) => t.title === 'synonyms' && t.value.split(', ').includes(name)),
+  );
+}
+
+async function getUndocumented(path, docs) {
+  try {
+    // load the code of pattern.mjs as a string
+    const code = await readFile(path, 'utf8');
+    return getExports(code).filter((name) => !isDocumented(name, docs));
+  } catch (err) {
+    return [`parse error: ${err.name}: ${err.message}`];
+  }
+}
+
+// read doc.json file
+const { docs } = JSON.parse(await readFile(resolve(__dirname, '..', 'doc.json'), 'utf8'));
+
+const paths = dependencyTree.toList({
+  filename: 'index.mjs',
+  // filename: 'packages/core/index.mjs',
+  directory: resolve(__dirname),
+  filter: (path) => !path.includes('node_modules'),
+});
+// const paths = ['../packages/core/pattern.mjs', '../packages/core/hap.mjs'].map((rel) => resolve(__dirname, rel));
+
+const undocumented = Object.fromEntries(
+  await Promise.all(paths.map(async (path) => [path.replace(resolve(__dirname, '..'), ''), await getUndocumented(path, docs)])),
+);
+
+console.log(JSON.stringify(undocumented, null, 2));