Generated JSON documentation no longer includes methods field.

[Me1000]

• Version: 13.6.0

PR #31086 Changed the markdown styling for documentation. This introduced a bug in the JSON documentation which gets generated with the release. Specifically the methods field is no longer there:

e.g. in 13.5.0:

  source: 'node/doc/api/assert.md',
  modules: [
    {
      textRaw: 'Assert',
      name: 'assert',
      introduced_in: 'v0.1.21',
      stability: 2,
      stabilityText: 'Stable',
      desc: '<p>The <code>assert</code> module provides a set of assertion functions for verifying\n' +
        'invariants. The module provides a recommended <code>strict</code> mode and a more\n' +
        'lenient legacy mode.</p>\n',
      classes: [Array],
      modules: [Array],
      methods: [Array],
      type: 'module',
      displayName: 'Assert'
    }
  ]
}

In 13.6.0 ▶️:

  source: 'node/doc/api/assert.md',
  modules: [
    {
      textRaw: 'Assert',
      name: 'assert',
      introduced_in: 'v0.1.21',
      stability: 2,
      stabilityText: 'Stable',
      desc: '<p>The <code>assert</code> module provides a set of assertion functions for verifying\n' +
        'invariants. The module provides a recommended <code>strict</code> mode and a more\n' +
        'lenient legacy mode.</p>\n',
      classes: [Array],
      modules: [Array],
      type: 'module',
      displayName: 'Assert'
    }
  ]
}

It looks like this regex no longer matched: https://github.com/nodejs/node/blob/master/tools/doc/json.js#L475

Since they're really only used for the HTML styling, I think a simple fix might be to just strip the tick marks here:

node/tools/doc/json.js

Line 482 in 9d5d4f8

const text = textJoin(header.children, file);

- const text = textJoin(header.children, file);
+ const text = textJoin(header.children, file).replace(/`/g, "");

I can submit a PR if others agree with this simple solution.

EDIT: Unfortunately that simple solution will not work. There were some existing headings with tick marks that parse incorrectly if they're removed. Continuing to investigate, but I'm still not super familiar with this code.

[Trott]

Yikes. Here's the relevant computed regexp: /^(?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w\.]+\\?\])\.?)*((?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w\.]+\\?\]))\([^)]*\)$/ Fun! Something in there needs to accommodate the backtick character.

[Trott]

@Me1000 Can you check if this patch fixes the problem for you? It seems to fix it for me.

diff --git a/tools/doc/json.js b/tools/doc/json.js
index e07486265c..9ec6394085 100644
--- a/tools/doc/json.js
+++ b/tools/doc/json.js
@@ -442,6 +442,8 @@ const maybeClassPropertyPrefix = '(?:Class Property: +)?';
 const maybeQuote = '[\'"]?';
 const notQuotes = '[^\'"]+';
 
+const maybeBacktick = '[`]?';
+
 // To include constructs like `readable\[Symbol.asyncIterator\]()`
 // or `readable.\_read(size)` (with Markdown escapes).
 const simpleId = r`(?:(?:\\?_)+|\b)\w+\b`;
@@ -472,7 +474,8 @@ const headingExpressions = [
     `${classMethodPrefix}${maybeAncestors}(${id})${callWithParams}$`, 'i') },
 
   { type: 'method', re: RegExp(
-    `^${maybeAncestors}(${id})${callWithParams}$`, 'i') },
+    // eslint-disable-next-line max-len
+    `^${maybeBacktick}${maybeAncestors}(${id})${callWithParams}${maybeBacktick}$`, 'i') },
 
   { type: 'property', re: RegExp(
     `^${maybeClassPropertyPrefix}${ancestors}(${id})${noCallOrProp}$`, 'i') },

Also, I don't suppose you've checked to see if any of the other elements (class, ctor, classMethod, event, property) have missing entries too?

[Trott]

#31294 should fix this problem for methods. Further research is probably necessary to see if this needs to be done for the other regular expressions ((class, ctor, classMethod, event, property) or not.

[Trott]

+const maybeBacktick = '[`]?';

Heh, I guess that could just be:

+const maybeBacktick = '`?';

[Trott]

Looks like this bug effects events too.

[Trott]

Class names too. Probably all of them. I'll add 'em to the PR.