tools: update JSON header parsing for backticks

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: #31290 PR-URL: #31294 Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
nodejs · Jan 16, 2020 · 49364b0 · 49364b0
1 parent 2285936
commit 49364b0
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 7 deletions.
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);