tmp

Author: flakey5

src/generators/json-all/index.mjs

@@ -35,13 +35,10 @@ export default {
     const generatedValue = {
       $schema: './node-doc-all-schema.jsonc',
       modules: [],
-      text: []
-    }
+      text: [],
+    };
 
-    const propertiesToIgnore = [
-      '$schema',
-      'source',
-    ]
+    const propertiesToIgnore = ['$schema', 'source'];
 
     input.forEach(section => {
       const copiedSection = {};
@@ -50,7 +47,7 @@ export default {
         if (!propertiesToIgnore.includes(key)) {
           copiedSection[key] = section[key];
         }
-      })
+      });
 
       switch (section.type) {
         case 'module':
@@ -62,7 +59,7 @@ export default {
         default:
           throw new TypeError(`unsupported root section type ${section.type}`);
       }
-    })
+    });
 
     if (output) {
       // Current directory path relative to the `index.mjs` file

src/generators/json-all/schema.jsonc

@@ -11,7 +11,7 @@
     },
     "text": {
       "type": "array",
-      "items": { "$ref": "../json/schema.jsonc/#/definitions/Text" }
-    }
+      "items": { "$ref": "../json/schema.jsonc/#/definitions/Text" },
+    },
   },
 }

src/generators/json/constants.mjs

@@ -0,0 +1 @@
+'use strict';

src/generators/json/generated.d.ts

@@ -34,16 +34,17 @@ export type Module = SectionBase & {
   properties?: Property[];
   [k: string]: unknown;
 };
+export type Text = SectionBase;
 /**
  * Node.js version number
  */
 export type NodeCoreVersion = string;
 export type Class = SectionBase & {
   type: 'class';
-  '@constructor'?: MethodSignature[];
-  methods?: Method[];
-  staticMethods?: Method[];
-  properties?: Property[];
+  '@constructor': MethodSignature[];
+  methods: Method[];
+  staticMethods: Method[];
+  properties: Property[];
   [k: string]: unknown;
 };
 /**
@@ -69,7 +70,6 @@ export type Property = SectionBase & {
   mutable?: boolean;
   [k: string]: unknown;
 };
-export type Text = SectionBase;
 
 /**
  * Common properties found at the root of each document.
@@ -97,6 +97,10 @@ export interface SectionBase {
    * Description of the section.
    */
   description?: string;
+  /**
+   * Sections that just hold further text on this section.
+   */
+  text?: Text[];
   /**
    * https://jsdoc.app/tags-example
    */

src/generators/json/index.mjs

@@ -27,7 +27,8 @@ export default {
   // This should be kept in sync with the JSON schema version
   version: '2.0.0',
 
-  description: 'TODO',
+  description:
+    'This generator is responsible for generating the JSON representation of the docs.',
 
   dependsOn: 'ast',
 
@@ -76,7 +77,7 @@ export default {
       if (output) {
         await writeFile(
           join(output, `${node.api}.json`),
-          JSON.stringify(section)
+          JSON.stringify(section, null, 2)
         );
       }
     });
@@ -86,13 +87,13 @@ export default {
       const baseDir = import.meta.dirname;
 
       // Read the contents of the JSON schema
-      const schemaString = await readFile(
-        join(baseDir, 'schema.jsonc'),
-        'utf8'
-      );
+      // const schemaString = await readFile(
+      //   join(baseDir, 'schema.jsonc'),
+      //   'utf8'
+      // );
 
-      // Parse the JSON schema into an object
-      const schema = await jsoncParse(schemaString);
+      // // Parse the JSON schema into an object
+      // const schema = await jsoncParse(schemaString);
 
       // Write the parsed JSON schema to the output directory
       // await writeFile(

src/generators/json/schema.jsonc

@@ -1,6 +1,10 @@
 {
-  // TODO vscode doesn't support 2020-12 yet
-  //  https://github.com/microsoft/vscode/issues/165219
+  /**
+   * NOTE: if you modify this, please:
+   *  - Bump the version in the $id property and in the generator
+   *  - Run `tools/generate-json-types.mjs`
+   */
+
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "[email protected]", // This should be kept in sync with the generator version
   "title": "Node.js API Documentation Schema",
@@ -142,7 +146,6 @@
               "items": { "$ref": "#/definitions/Property" },
             },
           },
-          // TODO what else to be required
           "required": ["type", "@module", "@see"],
         },
       ],

src/generators/json/utils/createMethodSection.mjs

@@ -9,13 +9,48 @@ import { findParentSection } from './findParentSection.mjs';
 
 export const createMethodSectionBuilder = () => {
   /**
+   * TODO docs
+   * @param {HierarchizedEntry} entry The AST entry
+   * @returns {Record<string, import('../generated.d.ts').MethodParameter> | undefined}
+   */
+  const parseParameters = entry => {
+    const [, ...nodes] = entry.content.children;
+
+    const listNode = nodes.find(node => node.type === 'list');
+
+    if (!listNode) {
+      // Method doesn't take in any parameters
+      return undefined;
+    }
+
+    /**
+     * @type {Record<string, import('../generated.d.ts').MethodParameter>}
+     */
+    const parameters = {};
+
+    listNode.children.forEach(({ children }) => {
+      // console.log(children)
+      // if (children.length !== 1) {
+      //   console.log(JSON.stringify(children, null, 2))
+      // }
+    });
+
+    return parameters;
+  };
+
+  /**
+   * TODO docs
    * @param {HierarchizedEntry} entry The AST entry
    * @param {import('../generated.d.ts').Method} section The method section
    */
   const parseSignatures = (entry, section) => {
     section.signatures = [];
 
-    
+    // Parse all the parameters and store them in a name:section map
+    const parameters = parseParameters(entry, section);
+
+    // Parse the value of entry.heading.data.text to get the order of parameters and which are optional
+    // console.log(entry.heading.data.text);
   };
 
   /**
@@ -26,18 +61,23 @@ export const createMethodSectionBuilder = () => {
   return (entry, section) => {
     parseSignatures(entry, section);
 
-    // TODO are there any other places that an exposed method can be defined?
     const parent = findParentSection(section, ['class', 'module']);
 
     // Add this section to the parent if it exists
     if (parent) {
-      if (!Array.isArray(parent.methods)) {
+      // Put static methods in `staticMethods` property and non-static methods
+      // in the `methods` property
+      const property = entry.heading.data.text.startsWith('Static method:')
+        ? 'staticMethods'
+        : 'methods';
+
+      if (!Array.isArray(parent[property])) {
         throw new TypeError(
-          `expected parent.methods to be an array, got type ${typeof parent.methods} instead (parent type=${parent.type})`
+          `expected parent[${property}] to be an array, got type ${typeof parent[property]} instead (parent type=${parent.type})`
         );
       }
 
-      parent.methods.push(section);
+      parent[property].push(section);
     }
   };
 };

src/generators/json/utils/createSection.mjs

@@ -18,7 +18,7 @@ export const createSectionBuilder = () => {
   const createMethodSection = createMethodSectionBuilder();
 
   /**
-   * TODO docs
+   * Creates the properties that exist in the root of a document
    * @param {ApiDocMetadataEntry} head The head metadata entry
    * @returns {import('../generated.d.ts').DocumentRoot}
    */
@@ -45,8 +45,10 @@ export const createSectionBuilder = () => {
     /**
      * @type {import('../types.d.ts').Section}
      */
-    const section = (createSectionBase(entry, parent?.type));
+    const section = createSectionBase(entry, parent?.type);
 
+    // Temporarily add the parent section to the section so we have access to
+    //  it and can easily traverse through them when we need to
     section.parent = parent;
 
     switch (section.type) {
@@ -76,6 +78,7 @@ export const createSectionBuilder = () => {
 
     handleChildren(entry, section);
 
+    // Remove the parent property we added to the section earlier
     delete section.parent;
 
     // if (parent) {

src/generators/json/utils/createSectionBase.mjs

@@ -1,6 +1,8 @@
 // @ts-check
 'use strict';
 
+import { enforceArray } from './enforceArray.mjs';
+
 /**
  * @typedef {import('../../legacy-json/types.d.ts').HierarchizedEntry} HierarchizedEntry
  */
@@ -20,17 +22,6 @@ const ENTRY_TO_SECTION_TYPE = /** @type {const} */ ({
   text: 'text',
 });
 
-/**
- * Converts a value to an array.
- * @template T
- * @param {T | T[]} val - The value to convert.
- * @returns {T[]} The value as an array.
- */
-const enforceArray = val => (Array.isArray(val) ? val : [val]);
-
-/**
- *
- */
 export const createSectionBaseBuilder = () => {
   /**
    * @param {import('mdast').RootContent} headingNode
@@ -118,7 +109,7 @@ export const createSectionBaseBuilder = () => {
   };
 
   /**
-   * TODO docs
+   * Adds the deprecated property to the section if needed.
    * @param {import('../generated.d.ts').SectionBase} section
    * @param {HierarchizedEntry} entry
    */
@@ -131,7 +122,7 @@ export const createSectionBaseBuilder = () => {
   };
 
   /**
-   * TODO docs
+   * Adds the stability property to the section.
    * @param {import('../generated.d.ts').SectionBase} section
    * @param {HierarchizedEntry} entry
    */
@@ -149,7 +140,7 @@ export const createSectionBaseBuilder = () => {
   };
 
   /**
-   * TODO docs
+   * Adds the properties relating to versioning to the section.
    * @param {import('../generated.d.ts').SectionBase} section
    * @param {HierarchizedEntry} entry
    */

src/generators/json/utils/enforceArray.mjs

@@ -0,0 +1,9 @@
+'use strict';
+
+/**
+ * Converts a value to an array.
+ * @template T
+ * @param {T | T[]} val - The value to convert.
+ * @returns {T[]} The value as an array.
+ */
+export const enforceArray = val => (Array.isArray(val) ? val : [val]);

src/generators/json/utils/findParentSection.mjs

@@ -1,15 +1,15 @@
 'use strict';
 
+import { enforceArray } from './enforceArray.mjs';
+
 /**
  * Finds the closest parent section with the specified type(s).
  * @param {import('../types.d.ts').Section} section
  * @param {import('../generated.d.ts').SectionBase['type'] | Array<import('../generated.d.ts').SectionBase['type']>} type
  * @returns {import('../types.d.ts').Section | undefined}
  */
 export function findParentSection(section, type) {
-  if (!Array.isArray(type)) {
-    type = [type];
-  }
+  type = enforceArray(type);
 
   let parent = section.parent;