From 8f9cb75120a1ace390b587a71ffd1796d633089b Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Thu, 3 May 2018 16:39:04 +0100 Subject: [PATCH] [ADF-2911] Improved error message handling in doc tools (#3267) --- lib/config/DocProcessor/docProcessor.js | 20 ++++++- lib/config/DocProcessor/tools/tsInfo.js | 73 ++++++++++++++++++----- lib/config/DocProcessor/tools/tsInfo.ts | 79 ++++++++++++++++++++----- 3 files changed, 142 insertions(+), 30 deletions(-) diff --git a/lib/config/DocProcessor/docProcessor.js b/lib/config/DocProcessor/docProcessor.js index 79075a1780..1e463f9d06 100644 --- a/lib/config/DocProcessor/docProcessor.js +++ b/lib/config/DocProcessor/docProcessor.js @@ -47,7 +47,10 @@ function aggPhase(aggData) { function updatePhase(filenames, aggData) { + var errorMessages; + for (var i = 0; i < filenames.length; i++) { + errorMessages = []; var pathname = filenames[i]; // path.resolve(srcFolder, filenames[i]); var src = fs.readFileSync(pathname); @@ -56,9 +59,13 @@ function updatePhase(filenames, aggData) { var modified = false; toolList.forEach(toolName => { - modified |= toolModules[toolName].updatePhase(tree, pathname, aggData); + modified |= toolModules[toolName].updatePhase(tree, pathname, aggData, errorMessages); }); + if (errorMessages.length > 0) { + showErrors(pathname, errorMessages); + } + if (modified) fs.writeFileSync(filenames[i], remark().use(frontMatter, {type: 'yaml', fence: '---'}).data("settings", {paddedTable: false, gfm: false}).stringify(tree)); @@ -67,6 +74,17 @@ function updatePhase(filenames, aggData) { } +function showErrors(filename, errorMessages) { + console.log(filename); + + errorMessages.forEach(message => { + console.log(" " + message); + }); + + console.log(""); +} + + function loadToolModules() { var mods = {}; var toolsFolderPath = path.resolve(__dirname, toolsFolderName); diff --git a/lib/config/DocProcessor/tools/tsInfo.js b/lib/config/DocProcessor/tools/tsInfo.js index ad551129e0..d47e09d8e7 100644 --- a/lib/config/DocProcessor/tools/tsInfo.js +++ b/lib/config/DocProcessor/tools/tsInfo.js @@ -16,9 +16,13 @@ var nameExceptions = { "tasklist.service": "TaskListService", "text-mask.component": "InputMaskDirective" }; +var undocMethodNames = { + "ngOnChanges": 1 +}; var PropInfo = /** @class */ (function () { function PropInfo(rawProp) { var _this = this; + this.errorMessages = []; this.name = rawProp.name; this.docText = rawProp.comment ? rawProp.comment.shortText : ""; this.docText = this.docText.replace(/[\n\r]+/g, " ").trim(); @@ -36,21 +40,29 @@ var PropInfo = /** @class */ (function () { _this.isInput = true; if (dec.arguments) { var bindingName = dec.arguments["bindingPropertyName"]; - //console.log(JSON.stringify(dec.arguments)); if (bindingName && (bindingName !== "")) _this.name = bindingName.replace(/['"]/g, ""); } - if (!_this.docText && !_this.isDeprecated) - console.log("Warning: Input \"" + rawProp.getFullName() + "\" has no doc text."); + if (!_this.docText && !_this.isDeprecated) { + _this.errorMessages.push("Warning: Input \"" + rawProp.name + "\" has no doc text."); + } } if (dec.name === "Output") { _this.isOutput = true; - if (!_this.docText && !_this.isDeprecated) - console.log("Warning: Output \"" + rawProp.getFullName() + "\" has no doc text."); + if (!_this.docText && !_this.isDeprecated) { + _this.errorMessages.push("Warning: Output \"" + rawProp.name + "\" has no doc text."); + } } }); } } + Object.defineProperty(PropInfo.prototype, "errors", { + get: function () { + return this.errorMessages; + }, + enumerable: true, + configurable: true + }); return PropInfo; }()); ; @@ -74,28 +86,33 @@ var ParamInfo = /** @class */ (function () { var MethodSigInfo = /** @class */ (function () { function MethodSigInfo(rawSig) { var _this = this; + this.errorMessages = []; this.name = rawSig.name; this.returnType = rawSig.type ? rawSig.type.toString() : ""; this.returnsSomething = this.returnType != "void"; if (rawSig.hasComment()) { this.docText = rawSig.comment.shortText + rawSig.comment.text; this.docText = this.docText.replace(/[\n\r]+/g, " ").trim(); - if (!this.docText) - console.log("Warning: method \"" + rawSig.name + "\" has no doc text."); + if (!this.docText) { + this.errorMessages.push("Warning: method \"" + rawSig.name + "\" has no doc text."); + } this.returnDocText = rawSig.comment.returns; this.returnDocText = this.returnDocText ? this.returnDocText.replace(/[\n\r]+/g, " ").trim() : ""; - if (this.returnDocText.toLowerCase() === "nothing") + if (this.returnDocText.toLowerCase() === "nothing") { this.returnsSomething = false; - if (this.returnsSomething && !this.returnDocText) - console.log("Warning: Return value of method \"" + rawSig.name + "\" has no doc text."); + } + if (this.returnsSomething && !this.returnDocText) { + this.errorMessages.push("Warning: Return value of method \"" + rawSig.name + "\" has no doc text."); + } this.isDeprecated = rawSig.comment.hasTag("deprecated"); } this.params = []; var paramStrings = []; if (rawSig.parameters) { rawSig.parameters.forEach(function (rawParam) { - if (!rawParam.comment || !rawParam.comment.text) - console.log("Warning: parameter \"" + rawParam.name + "\" of method \"" + rawSig.name + "\" has no doc text."); + if (!rawParam.comment || !rawParam.comment.text) { + _this.errorMessages.push("Warning: parameter \"" + rawParam.name + "\" of method \"" + rawSig.name + "\" has no doc text."); + } var param = new ParamInfo(rawParam); _this.params.push(param); paramStrings.push(param.combined); @@ -103,6 +120,13 @@ var MethodSigInfo = /** @class */ (function () { } this.signature = "(" + paramStrings.join(", ") + ")"; } + Object.defineProperty(MethodSigInfo.prototype, "errors", { + get: function () { + return this.errorMessages; + }, + enumerable: true, + configurable: true + }); return MethodSigInfo; }()); var ComponentInfo = /** @class */ (function () { @@ -116,7 +140,7 @@ var ComponentInfo = /** @class */ (function () { var methods = classRef.getChildrenByKind(typedoc_1.ReflectionKind.Method); this.methods = []; methods.forEach(function (method) { - if (!(method.flags.isPrivate || method.flags.isProtected)) { + if (!(method.flags.isPrivate || method.flags.isProtected || undocMethodNames[method.name])) { method.signatures.forEach(function (sig) { _this.methods.push(new MethodSigInfo(sig)); }); @@ -130,6 +154,24 @@ var ComponentInfo = /** @class */ (function () { }); this.hasMethods = methods.length > 0; } + Object.defineProperty(ComponentInfo.prototype, "errors", { + get: function () { + var combinedErrors = []; + this.methods.forEach(function (method) { + method.errors.forEach(function (err) { + combinedErrors.push(err); + }); + }); + this.properties.forEach(function (prop) { + prop.errors.forEach(function (err) { + combinedErrors.push(err); + }); + }); + return combinedErrors; + }, + enumerable: true, + configurable: true + }); return ComponentInfo; }()); function initPhase(aggData) { @@ -154,7 +196,7 @@ exports.readPhase = readPhase; function aggPhase(aggData) { } exports.aggPhase = aggPhase; -function updatePhase(tree, pathname, aggData) { +function updatePhase(tree, pathname, aggData, errorMessages) { var compName = angNameToClassName(path.basename(pathname, ".md")); var classRef = aggData.projData.findReflectionByName(compName); if (!classRef) { @@ -175,6 +217,9 @@ function updatePhase(tree, pathname, aggData) { newSection_1.push(after); return newSection_1; }); + compData.errors.forEach(function (err) { + errorMessages.push(err); + }); /* let templateName = classType[0] + ".liquid"; diff --git a/lib/config/DocProcessor/tools/tsInfo.ts b/lib/config/DocProcessor/tools/tsInfo.ts index d32d5ce311..d348c1ef91 100644 --- a/lib/config/DocProcessor/tools/tsInfo.ts +++ b/lib/config/DocProcessor/tools/tsInfo.ts @@ -37,6 +37,11 @@ let nameExceptions = { } +let undocMethodNames = { + "ngOnChanges": 1 +}; + + class PropInfo { name: string; type: string; @@ -47,7 +52,10 @@ class PropInfo { isOutput: boolean; isDeprecated: boolean; + errorMessages: string[]; + constructor(rawProp: DeclarationReflection) { + this.errorMessages = []; this.name = rawProp.name; this.docText = rawProp.comment ? rawProp.comment.shortText : ""; this.docText = this.docText.replace(/[\n\r]+/g, " ").trim(); @@ -69,25 +77,30 @@ class PropInfo { if (dec.arguments) { let bindingName = dec.arguments["bindingPropertyName"]; - //console.log(JSON.stringify(dec.arguments)); if (bindingName && (bindingName !== "")) this.name = bindingName.replace(/['"]/g, ""); } - if (!this.docText && !this.isDeprecated) - console.log(`Warning: Input "${rawProp.getFullName()}" has no doc text.`); + if (!this.docText && !this.isDeprecated) { + this.errorMessages.push(`Warning: Input "${rawProp.name}" has no doc text.`); + } } if (dec.name === "Output") { this.isOutput = true; - if (!this.docText && !this.isDeprecated) - console.log(`Warning: Output "${rawProp.getFullName()}" has no doc text.`); + if (!this.docText && !this.isDeprecated) { + this.errorMessages.push(`Warning: Output "${rawProp.name}" has no doc text.`); + } } }); } } + + get errors() { + return this.errorMessages; + } }; @@ -130,7 +143,11 @@ class MethodSigInfo { params: ParamInfo[]; isDeprecated: boolean; + errorMessages: string[]; + + constructor(rawSig: SignatureReflection) { + this.errorMessages = []; this.name = rawSig.name; this.returnType = rawSig.type ? rawSig.type.toString() : ""; this.returnsSomething = this.returnType != "void"; @@ -139,18 +156,21 @@ class MethodSigInfo { this.docText = rawSig.comment.shortText + rawSig.comment.text; this.docText = this.docText.replace(/[\n\r]+/g, " ").trim(); - if (!this.docText) - console.log(`Warning: method "${rawSig.name}" has no doc text.`); + if (!this.docText) { + this.errorMessages.push(`Warning: method "${rawSig.name}" has no doc text.`); + } this.returnDocText = rawSig.comment.returns; this.returnDocText = this.returnDocText ? this.returnDocText.replace(/[\n\r]+/g, " ").trim() : ""; - if (this.returnDocText.toLowerCase() === "nothing") + if (this.returnDocText.toLowerCase() === "nothing") { this.returnsSomething = false; + } + + if (this.returnsSomething && !this.returnDocText) { + this.errorMessages.push(`Warning: Return value of method "${rawSig.name}" has no doc text.`); + } - if (this.returnsSomething && !this.returnDocText) - console.log(`Warning: Return value of method "${rawSig.name}" has no doc text.`); - this.isDeprecated = rawSig.comment.hasTag("deprecated"); } @@ -159,8 +179,10 @@ class MethodSigInfo { if (rawSig.parameters) { rawSig.parameters.forEach(rawParam => { - if (!rawParam.comment || !rawParam.comment.text) - console.log(`Warning: parameter "${rawParam.name}" of method "${rawSig.name}" has no doc text.`); + if (!rawParam.comment || !rawParam.comment.text) { + this.errorMessages.push(`Warning: parameter "${rawParam.name}" of method "${rawSig.name}" has no doc text.`); + } + let param = new ParamInfo(rawParam); this.params.push(param); paramStrings.push(param.combined); @@ -169,6 +191,10 @@ class MethodSigInfo { this.signature = "(" + paramStrings.join(", ") + ")"; } + + get errors() { + return this.errorMessages; + } } @@ -192,7 +218,7 @@ class ComponentInfo { this.methods = []; methods.forEach(method =>{ - if (!(method.flags.isPrivate || method.flags.isProtected)) { + if (!(method.flags.isPrivate || method.flags.isProtected || undocMethodNames[method.name])) { method.signatures.forEach(sig => { this.methods.push(new MethodSigInfo(sig)); }); @@ -209,6 +235,24 @@ class ComponentInfo { this.hasMethods = methods.length > 0; } + + get errors() { + let combinedErrors = []; + + this.methods.forEach(method => { + method.errors.forEach(err => { + combinedErrors.push(err); + }) + }); + + this.properties.forEach(prop => { + prop.errors.forEach(err => { + combinedErrors.push(err); + }); + }); + + return combinedErrors; + } } @@ -239,7 +283,7 @@ export function aggPhase(aggData) { } -export function updatePhase(tree, pathname, aggData) { +export function updatePhase(tree, pathname, aggData, errorMessages) { let compName = angNameToClassName(path.basename(pathname, ".md")); let classRef = aggData.projData.findReflectionByName(compName); @@ -266,6 +310,11 @@ export function updatePhase(tree, pathname, aggData) { newSection.push(after); return newSection; }); + + compData.errors.forEach(err => { + errorMessages.push(err); + }) + /* let templateName = classType[0] + ".liquid";