Skip to content

Commit

Permalink
tools: update JSON header parsing for backticks
Browse files Browse the repository at this point in the history
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 <riclau@uk.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
Trott authored and codebytere committed Mar 17, 2020
1 parent 597431b commit 20f857f
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 7 deletions.
68 changes: 68 additions & 0 deletions test/doctool/test-doctool-json.js
Original file line number Diff line number Diff line change
Expand Up @@ -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'
}
]
}
}
];

Expand Down
13 changes: 13 additions & 0 deletions test/fixtures/doc_with_backticks_in_headings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Fhqwhgads

## Class: `ComeOn`

## `everybody.to(limit)`

## Event: `'FHQWHfest'`

## Constructor: `new Fhqwhgads()`

## Class Method: `Fhqwhgads.again()`

## `Fqhqwhgads.fullName`
18 changes: 11 additions & 7 deletions tools/doc/json.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`;
Expand All @@ -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);
Expand Down

0 comments on commit 20f857f

Please sign in to comment.