tmp

Author: flakey5

src/generators/json-all/__tests__/version.test.mjs

@@ -0,0 +1,17 @@
+'use strict';
+
+import test from 'node:test';
+import assert from 'node:assert';
+import jsonAll from '../../json-all/index.mjs';
+import json from '../index.mjs';
+import { generateJsonSchema } from '../util/generateJsonSchema.mjs';
+
+test('json-all generator matches json generator version match', () => {
+  assert.strictEqual(jsonAll.version, json.version);
+});
+
+test('schema version matches generator version', () => {
+  const schema = generateJsonSchema();
+
+  assert.strictEqual(schema.$id, `nodejs-api-doc-all@v${jsonAll.version}`);
+});

src/generators/json-all/util/generateJsonSchema.mjs

@@ -1,15 +1,13 @@
-// @ts-check
 'use strict';
 
 import { DOC_NODE_VERSION } from '../../../constants.mjs';
+import jsonAll from '../index.mjs';
 
 const JSON_SCHEMA_URL = `https://nodejs.org/docs/${DOC_NODE_VERSION}/api/node-doc-schema.json`;
 
 export const generateJsonSchema = () => ({
   $schema: 'http://json-schema.org/draft-07/schema#',
-  // This should be kept in sync with the generator version for this generator
-  // AND the `json` generator and schema
-  $id: '[email protected]', // This should be kept in sync with the generator version.
+  $id: `nodejs-api-doc-all@${jsonAll.version}`,
   title: 'Node.js API Documentation Schema (All)',
   readOnly: true,
 

src/generators/json/__tests__/version.test.mjs

@@ -0,0 +1,18 @@
+'use strict';
+
+import test from 'node:test';
+import assert from 'node:assert';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as jsoncParse } from 'jsonc-parser';
+import json from '../index.mjs';
+
+test('schema version matches generator version ', async () => {
+  const schemaString = await readFile(
+    join(import.meta.dirname, '..', 'schema.jsonc'),
+    'utf8'
+  );
+  const schema = await jsoncParse(schemaString);
+
+  assert.strictEqual(schema.$id, `nodejs-api-doc@v${json.version}`);
+});

src/generators/json/constants.mjs

@@ -5,3 +5,10 @@ export const DEFAULT_EXPRESSION = /^(D|d)efault(s|):$/;
 
 // Grabs the type and description of one of the formats for event types
 export const EVENT_TYPE_DESCRIPTION_EXTRACTOR = /{(.*)}(.*)/;
+
+// Grabs return type and optional description for a method signature
+// Accepts the following:
+// Returns: {string}
+// Returns {string}
+// Returns: {string} bla bla bla
+export const METHOD_RETURN_TYPE_EXTRACTOR = /^Returns(:?) {(.*)}( .*)?$/;

src/generators/json/generated.d.ts

@@ -163,10 +163,7 @@ export interface Change {
 }
 export interface MethodSignature {
   parameters?: MethodParameter[];
-  /**
-   * The method signature's return type.
-   */
-  '@returns'?: string | [string, ...string[]];
+  '@returns'?: MethodReturnType;
   [k: string]: unknown;
 }
 export interface MethodParameter {
@@ -185,3 +182,14 @@ export interface MethodParameter {
   '@default'?: string;
   [k: string]: unknown;
 }
+/**
+ * A method signature's return type.
+ */
+export interface MethodReturnType {
+  description?: string;
+  /**
+   * The method signature's return type.
+   */
+  '@type': string | [string, ...string[]];
+  [k: string]: unknown;
+}

src/generators/json/schema.jsonc

@@ -232,22 +232,9 @@
         //   "$ref": "https://json-schema.org/draft-07/schema#",
         // },
         "@returns": {
-          "description": "The method signature's return type.",
-          "oneOf": [
-            {
-              "type": "string",
-              "examples": ["string"],
-            },
-            {
-              "type": "array",
-              "items": { "type": "string" },
-              "examples": [["string", "Promise<string>"]],
-              "minItems": 1,
-            },
-          ],
+          "$ref": "#/definitions/MethodReturnType",
         },
       },
-      "required": [],
     },
 
     "MethodParameter": {
@@ -285,6 +272,32 @@
       "required": ["@name", "@type"],
     },
 
+    "MethodReturnType": {
+      "type": "object",
+      "description": "A method signature's return type.",
+      "properties": {
+        "description": {
+          "type": "string",
+        },
+        "@type": {
+          "description": "The method signature's return type.",
+          "oneOf": [
+            {
+              "type": "string",
+              "examples": ["string"],
+            },
+            {
+              "type": "array",
+              "items": { "type": "string" },
+              "examples": [["string", "Promise<string>"]],
+              "minItems": 1,
+            },
+          ],
+        },
+      },
+      "required": ["@type"],
+    },
+
     "Global": {
       "type": "object",
       "properties": {},