tools: update JSON header parsing for backticks

Trott · Trott · commit be46a7257b36 · 2020-01-12T07:10:33.000-08:00
Methods, events, and so on in headers in our documentation may (and should) be set off with backticks in the raw markdown. When that happens, the headers is misinterpreted by tools/json.js as not being a method or event. Update the JSON tool generator to accommodate backticks in this situation and add a test for this situation. Fixes: nodejs#31290 PR-URL: nodejs#31294 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/test/doctool/test-doctool-json.js b/test/doctool/test-doctool-json.js
@@ -157,6 +157,74 @@ const testData = [
         }
       ]
     }
+  },
+  {
+    file: fixtures.path('doc_with_backticks_in_headings.md'),
+    json: {
+      type: 'module',
+      source: 'foo',
+      modules: [
+        {
+          textRaw: 'Fhqwhgads',
+          name: 'fhqwhgads',
+          properties: [
+            {
+              name: 'fullName',
+              textRaw: '`Fqhqwhgads.fullName`'
+            }
+          ],
+          classMethods: [
+            {
+              name: 'again',
+              signatures: [
+                {
+                  params: []
+                }
+              ],
+              textRaw: 'Class Method: `Fhqwhgads.again()`',
+              type: 'classMethod'
+            }
+          ],
+          classes: [
+            {
+              textRaw: 'Class: `ComeOn`',
+              type: 'class',
+              name: 'ComeOn'
+            }
+          ],
+          ctors: [
+            {
+              name: 'Fhqwhgads',
+              signatures: [
+                {
+                  params: []
+                }
+              ],
+              textRaw: 'Constructor: `new Fhqwhgads()`',
+              type: 'ctor'
+            }
+          ],
+          methods: [
+            {
+              textRaw: '`everybody.to(limit)`',
+              type: 'method',
+              name: 'to',
+              signatures: [{ params: [] }]
+            }
+          ],
+          events: [
+            {
+              textRaw: "Event: `'FHQWHfest'`",
+              type: 'event',
+              name: 'FHQWHfest',
+              params: []
+            }
+          ],
+          type: 'module',
+          displayName: 'Fhqwhgads'
+        }
+      ]
+    }
   }
 ];
 
diff --git a/test/fixtures/doc_with_backticks_in_headings.md b/test/fixtures/doc_with_backticks_in_headings.md
@@ -0,0 +1,13 @@
+# Fhqwhgads
+
+## Class: `ComeOn`
+
+## `everybody.to(limit)`
+
+## Event: `'FHQWHfest'`
+
+## Constructor: `new Fhqwhgads()`
+
+## Class Method: `Fhqwhgads.again()`
+
+## `Fqhqwhgads.fullName`
diff --git a/tools/doc/json.js b/tools/doc/json.js
@@ -435,13 +435,15 @@ const r = String.raw;
 
 const eventPrefix = '^Event: +';
 const classPrefix = '^[Cc]lass: +';
-const ctorPrefix = '^(?:[Cc]onstructor: +)?new +';
+const ctorPrefix = '^(?:[Cc]onstructor: +)?`?new +';
 const classMethodPrefix = '^Class Method: +';
 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`;
@@ -458,25 +460,27 @@ const noCallOrProp = '(?![.[(])';
 
 const maybeExtends = `(?: +extends +${maybeAncestors}${classId})?`;
 
+/* eslint-disable max-len */
 const headingExpressions = [
   { type: 'event', re: RegExp(
-    `${eventPrefix}${maybeQuote}(${notQuotes})${maybeQuote}$`, 'i') },
+    `${eventPrefix}${maybeBacktick}${maybeQuote}(${notQuotes})${maybeQuote}${maybeBacktick}$`, 'i') },
 
   { type: 'class', re: RegExp(
-    `${classPrefix}(${maybeAncestors}${classId})${maybeExtends}$`, '') },
+    `${classPrefix}${maybeBacktick}(${maybeAncestors}${classId})${maybeExtends}${maybeBacktick}$`, '') },
 
   { type: 'ctor', re: RegExp(
-    `${ctorPrefix}(${maybeAncestors}${classId})${callWithParams}$`, '') },
+    `${ctorPrefix}(${maybeAncestors}${classId})${callWithParams}${maybeBacktick}$`, '') },
 
   { type: 'classMethod', re: RegExp(
-    `${classMethodPrefix}${maybeAncestors}(${id})${callWithParams}$`, 'i') },
+    `${classMethodPrefix}${maybeBacktick}${maybeAncestors}(${id})${callWithParams}${maybeBacktick}$`, 'i') },
 
   { type: 'method', re: RegExp(
-    `^${maybeAncestors}(${id})${callWithParams}$`, 'i') },
+    `^${maybeBacktick}${maybeAncestors}(${id})${callWithParams}${maybeBacktick}$`, 'i') },
 
   { type: 'property', re: RegExp(
-    `^${maybeClassPropertyPrefix}${ancestors}(${id})${noCallOrProp}$`, 'i') },
+    `^${maybeClassPropertyPrefix}${maybeBacktick}${ancestors}(${id})${maybeBacktick}${noCallOrProp}$`, 'i') },
 ];
+/* eslint-enable max-len */
 
 function newSection(header, file) {
   const text = textJoin(header.children, file);
