resolve review

Author: avivkeller

src/generators/legacy-json-all/index.mjs

@@ -21,6 +21,12 @@ export default {
 
   dependsOn: 'legacy-json',
 
+  /**
+   *
+   * @param input
+   * @param root0
+   * @param root0.output
+   */
   async generate(input, { output }) {
     /**
      * The consolidated output object that will contain

src/generators/legacy-json/constants.mjs

@@ -16,3 +16,21 @@ export const DEFAULT_EXPRESSION = /\s*\*\*Default:\*\*\s*([^]+)$/i;
 // Grabs the parameters from a method's signature
 //  ex/ 'new buffer.Blob([sources[, options]])'.match(PARAM_EXPRESSION) === ['([sources[, options]])', '[sources[, options]]']
 export const PARAM_EXPRESSION = /\((.+)\);?$/;
+
+// The plurals associated with each section type.
+export const SECTION_TYPE_PLURALS = {
+  module: 'modules',
+  misc: 'miscs',
+  class: 'classes',
+  method: 'methods',
+  property: 'properties',
+  global: 'globals',
+  example: 'examples',
+  ctor: 'signatures',
+  classMethod: 'classMethods',
+  event: 'events',
+  var: 'vars',
+};
+
+// The keys to not promote when promoting children.
+export const UNPROMOTED_KEYS = ['textRaw', 'name', 'type', 'desc', 'miscs'];

src/generators/legacy-json/index.mjs

@@ -7,12 +7,12 @@ import { createSectionBuilder } from './utils/buildSection.mjs';
 
 /**
  * This generator is responsible for generating the legacy JSON files for the
- *  legacy API docs for retro-compatibility. It is to be replaced while we work
- *  on the new schema for this file.
+ * legacy API docs for retro-compatibility. It is to be replaced while we work
+ * on the new schema for this file.
  *
  * This is a top-level generator, intaking the raw AST tree of the api docs.
  * It generates JSON files to the specified output directory given by the
- *  config.
+ * config.
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
  *
@@ -27,6 +27,12 @@ export default {
 
   dependsOn: 'ast',
 
+  /**
+   *
+   * @param input
+   * @param root0
+   * @param root0.output
+   */
   async generate(input, { output }) {
     const buildSection = createSectionBuilder();
 

src/generators/legacy-json/utils/buildHierarchy.mjs

@@ -3,6 +3,7 @@
  *
  * @param {ApiDocMetadataEntry} entry
  * @param {ApiDocMetadataEntry[]} entry
+ * @param entries
  * @param {number} startIdx
  * @returns {import('../types.d.ts').HierarchizedEntry}
  */
@@ -29,19 +30,19 @@ function findParent(entry, entries, startIdx) {
 
 /**
  * We need the files to be in a hierarchy based off of depth, but they're
- *  given to us flattened. So, let's fix that.
+ * given to us flattened. So, let's fix that.
  *
  * Assuming that {@link entries} is in the same order as the elements are in
- *  the markdown, we can use the entry's depth property to reassemble the
- *  hierarchy.
+ * the markdown, we can use the entry's depth property to reassemble the
+ * hierarchy.
  *
  * If depth <= 1, it's a top-level element (aka a root).
  *
  * If it's depth is greater than the previous entry's depth, it's a child of
- *  the previous entry. Otherwise (if it's less than or equal to the previous
- *  entry's depth), we need to find the entry that it was the greater than. We
- *  can do this by just looping through entries in reverse starting at the
- *  current index - 1.
+ * the previous entry. Otherwise (if it's less than or equal to the previous
+ * entry's depth), we need to find the entry that it was the greater than. We
+ * can do this by just looping through entries in reverse starting at the
+ * current index - 1.
  *
  * @param {Array<ApiDocMetadataEntry>} entries
  * @returns {Array<import('../types.d.ts').HierarchizedEntry>}

src/generators/legacy-json/utils/buildSection.mjs

@@ -2,22 +2,7 @@ import { buildHierarchy } from './buildHierarchy.mjs';
 import { getRemarkRehype } from '../../../utils/remark.mjs';
 import { transformNodesToString } from '../../../utils/unist.mjs';
 import { parseList } from './parseList.mjs';
-
-const sectionTypePlurals = {
-  module: 'modules',
-  misc: 'miscs',
-  class: 'classes',
-  method: 'methods',
-  property: 'properties',
-  global: 'globals',
-  example: 'examples',
-  ctor: 'signatures',
-  classMethod: 'classMethods',
-  event: 'events',
-  var: 'vars',
-};
-
-const unpromotedKeys = ['textRaw', 'name', 'type', 'desc', 'miscs'];
+import { SECTION_TYPE_PLURALS, UNPROMOTED_KEYS } from '../constants.mjs';
 
 /**
  * Converts a value to an array.
@@ -27,6 +12,9 @@ const unpromotedKeys = ['textRaw', 'name', 'type', 'desc', 'miscs'];
  */
 const enforceArray = val => (Array.isArray(val) ? val : [val]);
 
+/**
+ *
+ */
 export const createSectionBuilder = () => {
   const html = getRemarkRehype();
 
@@ -117,7 +105,7 @@ export const createSectionBuilder = () => {
    * @param {import('../types.d.ts').Section} parent - The parent section.
    */
   const addToParent = (section, parent) => {
-    const key = sectionTypePlurals[section.type] || 'miscs';
+    const key = SECTION_TYPE_PLURALS[section.type] || 'miscs';
 
     parent[key] ??= [];
     parent[key].push(section);
@@ -133,7 +121,7 @@ export const createSectionBuilder = () => {
     if (section.type === 'misc' && parent.type !== 'misc') {
       Object.entries(section).forEach(([key, value]) => {
         // Only promote certain keys
-        if (!unpromotedKeys.includes(key)) {
+        if (!UNPROMOTED_KEYS.includes(key)) {
           // Merge the section's properties into the parent section
           parent[key] = parent[key]
             ? // If the parent already has this key, concatenate the values

src/generators/legacy-json/utils/parseSignature.mjs

@@ -109,6 +109,7 @@ function findParameter(parameterName, index, markdownParameters) {
 /**
  * @param {string[]} declaredParameters
  * @param {Array<import('../types.d.ts').ParameterList>} parameters
+ * @param markdownParameters
  */
 function parseParameters(declaredParameters, markdownParameters) {
   /**