Skip to content

Commit

Permalink
[doclint] be more permissive with syntax
Browse files Browse the repository at this point in the history
This patch adds a helpful message if the 'returns' statement is somehow
mistyped.

References puppeteer#14.
  • Loading branch information
aslushnikov committed Jul 15, 2017
1 parent 6eac22d commit 3b5dbe2
Show file tree
Hide file tree
Showing 4 changed files with 25 additions and 7 deletions.
22 changes: 16 additions & 6 deletions utils/doclint/MDBuilder.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ class MDOutline {

// Extract headings.
await page.setContent(html);
const classes = await page.evaluate(() => {
const {classes, errors} = await page.evaluate(() => {
let classes = [];
let currentClass = {};
let member = {};
let errors = [];
for (let element of document.body.querySelectorAll('h3, h4, h4 + ul > li')) {
if (element.matches('h3')) {
currentClass = {
Expand All @@ -39,18 +40,27 @@ class MDOutline {
currentClass.members.push(member);
} else if (element.matches('li') && element.firstChild.matches && element.firstChild.matches('code')) {
member.args.push(element.firstChild.textContent);
} else if (element.matches('li') && element.firstChild.nodeType === Element.TEXT_NODE && element.firstChild.textContent.startsWith('returns: ')) {
} else if (element.matches('li') && element.firstChild.nodeType === Element.TEXT_NODE && element.firstChild.textContent.toLowerCase().startsWith('retur')) {
member.hasReturn = true;
const expectedText = 'returns: ';
let actualText = element.firstChild.textContent;
let angleIndex = actualText.indexOf('<');
let spaceIndex = actualText.indexOf(' ');
angleIndex = angleIndex === -1 ? angleText.length : angleIndex;
spaceIndex = spaceIndex === -1 ? spaceIndex.length : spaceIndex + 1;
actualText = actualText.substring(0, Math.min(angleIndex, spaceIndex));
if (actualText !== expectedText)
errors.push(`${member.name} has mistyped 'return' type declaration: expected exactly '${expectedText}', found '${actualText}'.`);
}
}
return classes;
return {classes, errors};
});
return new MDOutline(classes);
return new MDOutline(classes, errors);
}

constructor(classes) {
constructor(classes, errors) {
this.classes = [];
this.errors = [];
this.errors = errors;
const classHeading = /^class: (\w+)$/;
const constructorRegex = /^new (\w+)\((.*)\)$/;
const methodRegex = /^(\w+)\.(\w+)\((.*)\)$/;
Expand Down
2 changes: 2 additions & 0 deletions utils/doclint/test/08-return/doc.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@
#### foo.returnNothing()
- returns: <[number]>

#### foo.www()
- returns <[string]>
5 changes: 5 additions & 0 deletions utils/doclint/test/08-return/foo.js
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ class Foo {
e();
}

www() {
if (1 === 1)
return 'df';
}

async asyncFunction() {
}
}
3 changes: 2 additions & 1 deletion utils/doclint/test/golden/08-return.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
[MarkDown] Async method Foo.asyncFunction should describe return type Promise
[MarkDown] Method Foo.return42 is missing return type description
[MarkDown] Method Foo.returnNothing has unneeded description of return type
[MarkDown] Method Foo.returnNothing has unneeded description of return type
[MarkDown] foo.www() has mistyped 'return' type declaration: expected exactly 'returns: ', found 'returns '.

0 comments on commit 3b5dbe2

Please sign in to comment.