[ADF-2911] Improved error message handling in doc tools (#3267)

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);

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)
+                    if (!_this.docText && !_this.isDeprecated) {
-                        console.log("Warning: Input \"" + rawProp.getFullName() + "\" has no doc text.");
+                        _this.errorMessages.push("Warning: Input \"" + rawProp.name + "\" has no doc text.");
+                    }
                 }
                 if (dec.name === "Output") {
                     _this.isOutput = true;
-                    if (!_this.docText && !_this.isDeprecated)
+                    if (!_this.docText && !_this.isDeprecated) {
-                        console.log("Warning: Output \"" + rawProp.getFullName() + "\" has no doc text.");
+                        _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)
+            if (!this.docText) {
-                console.log("Warning: method \"" + rawSig.name + "\" has no doc text.");
+                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)
+                if (!rawParam.comment || !rawParam.comment.text) {
-                    console.log("Warning: parameter \"" + rawParam.name + "\" of method \"" + rawSig.name + "\" has no doc 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";
 

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)
+                    if (!this.docText && !this.isDeprecated) {
-                        console.log(`Warning: Input "${rawProp.getFullName()}" has no doc text.`);
+                        this.errorMessages.push(`Warning: Input "${rawProp.name}" has no doc text.`);
+                    }
                 }
 
                 if (dec.name === "Output") {
                     this.isOutput = true;
 
-                    if (!this.docText && !this.isDeprecated)
+                    if (!this.docText && !this.isDeprecated) {
-                        console.log(`Warning: Output "${rawProp.getFullName()}" has no doc text.`);
+                        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,17 +156,20 @@ class MethodSigInfo {
             this.docText = rawSig.comment.shortText + rawSig.comment.text;
             this.docText = this.docText.replace(/[\n\r]+/g, " ").trim();
             
-            if (!this.docText)
+            if (!this.docText) {
-                console.log(`Warning: method "${rawSig.name}" has no doc text.`);
+                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)
+            if (this.returnsSomething && !this.returnDocText) {
-                console.log(`Warning: Return value of method "${rawSig.name}" has no doc text.`);
+                this.errorMessages.push(`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)
+                if (!rawParam.comment || !rawParam.comment.text) {
-                console.log(`Warning: parameter "${rawParam.name}" of method "${rawSig.name}" has no doc 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";