puppeteer/utils/doclint/Documentation.js
Andrey Lushnikov 235001bab3 [doclint] validate return statements
This patch teaches doclint to validate presence of return statements.
It also adds a bunch of documentation to the api.md.

References #14.
2017-07-14 13:04:15 -07:00

245 lines
7.4 KiB
JavaScript

class Documentation {
/**
* @param {!Array<!Documentation.Class>} clasesArray
*/
constructor(classesArray) {
this.classesArray = classesArray;
this.classes = new Map();
for (let cls of classesArray)
this.classes.set(cls.name, cls);
}
/**
* @param {!Documentation} actual
* @param {!Documentation} expected
* @return {!Array<string>}
*/
static diff(actual, expected) {
const errors = [];
const actualClasses = Array.from(actual.classes.keys()).sort();
const expectedClasses = Array.from(expected.classes.keys()).sort();
let classesDiff = diff(actualClasses, expectedClasses);
for (let className of classesDiff.extra)
errors.push(`Non-existing class found: ${className}`);
for (let className of classesDiff.missing)
errors.push(`Class not found: ${className}`);
for (let className of classesDiff.equal) {
const actualClass = actual.classes.get(className);
const expectedClass = expected.classes.get(className);
const actualMethods = Array.from(actualClass.methods.keys()).sort();
const expectedMethods = Array.from(expectedClass.methods.keys()).sort();
const methodDiff = diff(actualMethods, expectedMethods);
for (let methodName of methodDiff.extra)
errors.push(`Non-existing method found: ${className}.${methodName}()`);
for (let methodName of methodDiff.missing)
errors.push(`Method not found: ${className}.${methodName}()`);
for (let methodName of methodDiff.equal) {
const actualMethod = actualClass.methods.get(methodName);
const expectedMethod = expectedClass.methods.get(methodName);
if (actualMethod.hasReturn !== expectedMethod.hasReturn) {
if (actualMethod.hasReturn)
errors.push(`Method ${className}.${methodName} has unneeded description of return type`);
else if (!expectedMethod.async)
errors.push(`Method ${className}.${methodName} is missing return type description`);
else
errors.push(`Async method ${className}.${methodName} should describe return type Promise`);
}
const actualArgs = Array.from(actualMethod.args.keys());
const expectedArgs = Array.from(expectedMethod.args.keys());
const argDiff = diff(actualArgs, expectedArgs);
if (argDiff.extra.length || argDiff.missing.length) {
let text = [`Method ${className}.${methodName}() fails to describe its parameters:`];
for (let arg of argDiff.missing)
text.push(`- Argument not found: ${arg}`);
for (let arg of argDiff.extra)
text.push(`- Non-existing argument found: ${arg}`);
errors.push(text.join('\n'));
}
}
const actualProperties = Array.from(actualClass.properties.keys()).sort();
const expectedProperties = Array.from(expectedClass.properties.keys()).sort();
const propertyDiff = diff(actualProperties, expectedProperties);
for (let propertyName of propertyDiff.extra)
errors.push(`Non-existing property found: ${className}.${propertyName}`);
for (let propertyName of propertyDiff.missing)
errors.push(`Property not found: ${className}.${propertyName}`);
}
return errors;
}
/**
* @param {!Documentation} doc
* @return {!Array<string>}
*/
static validate(doc) {
const errors = [];
let classes = new Set();
// Report duplicates.
for (let cls of doc.classesArray) {
if (classes.has(cls.name))
errors.push(`Duplicate declaration of class ${cls.name}`);
classes.add(cls.name);
let members = new Set();
for (let member of cls.membersArray) {
if (members.has(member.name))
errors.push(`Duplicate declaration of method ${cls.name}.${member.name}()`);
members.add(member.name);
let args = new Set();
for (let arg of member.argsArray) {
if (args.has(arg.name))
errors.push(`Duplicate declaration of argument ${cls.name}.${member.name} "${arg.name}"`);
args.add(arg.name);
}
}
}
return errors;
}
}
Documentation.Class = class {
/**
* @param {string} name
* @param {!Array<!Documentation.Member>} membersArray
*/
constructor(name, membersArray) {
this.name = name;
this.membersArray = membersArray;
this.members = new Map();
this.properties = new Map();
this.methods = new Map();
for (let member of membersArray) {
this.members.set(member.name, member);
if (member.type === 'method')
this.methods.set(member.name, member);
else if (member.type === 'property')
this.properties.set(member.name, member);
}
}
};
Documentation.Member = class {
/**
* @param {string} type
* @param {string} name
* @param {!Array<!Documentation.Argument>} argsArray
* @param {boolean} hasReturn
* @param {boolean} async
*/
constructor(type, name, argsArray, hasReturn, async) {
this.type = type;
this.name = name;
this.argsArray = argsArray;
this.args = new Map();
this.hasReturn = hasReturn;
this.async = async;
for (let arg of argsArray)
this.args.set(arg.name, arg);
}
/**
* @param {string} name
* @param {!Array<!Documentation.Argument>} argsArray
* @param {boolean} hasReturn
* @return {!Documentation.Member}
*/
static createMethod(name, argsArray, hasReturn, async) {
return new Documentation.Member('method', name, argsArray, hasReturn, async);
}
/**
* @param {string} name
* @return {!Documentation.Member}
*/
static createProperty(name) {
return new Documentation.Member('property', name, [], false, false);
}
};
Documentation.Argument = class {
/**
* @param {string} name
*/
constructor(name) {
this.name = name;
}
};
/**
* @param {!Array<string>} actual
* @param {!Array<string>} expected
* @return {{extra: !Array<string>, missing: !Array<string>, equal: !Array<string>}}
*/
function diff(actual, expected) {
const N = actual.length;
const M = expected.length;
if (N === 0 && M === 0)
return { extra: [], missing: [], equal: []};
if (N === 0)
return {extra: [], missing: expected.slice(), equal: []};
if (M === 0)
return {extra: actual.slice(), missing: [], equal: []};
let d = new Array(N);
let bt = new Array(N);
for (let i = 0; i < N; ++i) {
d[i] = new Array(M);
bt[i] = new Array(M);
for (let j = 0; j < M; ++j) {
const top = val(i - 1, j);
const left = val(i, j - 1);
if (top > left) {
d[i][j] = top;
bt[i][j] = 'extra';
} else {
d[i][j] = left;
bt[i][j] = 'missing';
}
let diag = val(i - 1, j - 1);
if (actual[i] === expected[j] && d[i][j] < diag + 1) {
d[i][j] = diag + 1;
bt[i][j] = 'eq';
}
}
}
// Backtrack results.
let i = N - 1;
let j = M - 1;
let missing = [];
let extra = [];
let equal = [];
while (i >= 0 && j >= 0) {
switch (bt[i][j]) {
case 'extra':
extra.push(actual[i]);
i -= 1;
break;
case 'missing':
missing.push(expected[j]);
j -= 1;
break;
case 'eq':
equal.push(actual[i]);
i -= 1;
j -= 1;
break;
}
}
while (i >= 0)
extra.push(actual[i--]);
while (j >= 0)
missing.push(expected[j--]);
extra.reverse();
missing.reverse();
equal.reverse();
return {extra, missing, equal};
function val(i, j) {
return i < 0 || j < 0 ? 0 : d[i][j];
}
}
module.exports = Documentation;