[ADF-2557] Added return tag support and error messages (#3127)

* [ADF-2557] Added return tag support and error messages

* [ADF-2557] Set doc tool config to use index script correctly

lib/config/DocProcessor/doctool.config.json

@@ -1,5 +1,5 @@
 {
     "enabledTools": [
-        "tsInfo"
+        "index"
     ]
 }

lib/config/DocProcessor/templates/service.liquid

@@ -4,7 +4,7 @@
 
 {% for meth in methods %}- `{{meth.name}}{{meth.signature}}: {{meth.returnType}}`<br/>
   {{meth.docText}}
-  {% for param in meth.params %}   - `{{param.combined}}` - {% if param.isOptional %}(Optional){% endif %}{{param.docText}}
+{% for param in meth.params %}   - `{{param.combined}}` - {% if param.isOptional %}(Optional){% endif %}{{param.docText}}
-{% endfor %}
+{% endfor %}   - **Returns** `{{meth.returnType}}` - {{meth.returnDocText}}
 {% endfor %}
 {% endif %}

lib/config/DocProcessor/tools/tsInfo.js

@@ -7,7 +7,7 @@ var remark = require("remark");
 var frontMatter = require("remark-frontmatter");
 var liquid = require("liquidjs");
 var typedoc_1 = require("typedoc");
-var libFolders = ["content-services"]; //["core", "content-services", "process-services", "insights"];
+var libFolders = ["core", "content-services", "process-services", "insights"];
 var templateFolder = path.resolve(".", "config", "DocProcessor", "templates");
 var excludePatterns = [
     "**/*.spec.ts"
@@ -21,16 +21,22 @@ var PropInfo = /** @class */ (function () {
         var _this = this;
         this.name = rawProp.name;
         this.docText = rawProp.comment ? rawProp.comment.shortText : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
+        this.docText = this.docText.replace(/[\n\r]+/g, " ").trim();
         this.defaultValue = rawProp.defaultValue || "";
         this.defaultValue = this.defaultValue.replace(/\|/, "\\|");
         this.type = rawProp.type ? rawProp.type.toString() : "";
         if (rawProp.decorators) {
             rawProp.decorators.forEach(function (dec) {
-                if (dec.name === "Input")
+                if (dec.name === "Input") {
                     _this.isInput = true;
-                if (dec.name === "Output")
+                    if (!_this.docText)
+                        console.log("Warning: Input \"" + rawProp.getFullName() + "\" has no doc text.");
+                }
+                if (dec.name === "Output") {
                     _this.isOutput = true;
+                    if (!_this.docText)
+                        console.log("Warning: Output \"" + rawProp.getFullName() + "\" has no doc text.");
+                }
             });
         }
         this.isDeprecated = rawProp.comment && rawProp.comment.hasTag("deprecated");
@@ -44,7 +50,7 @@ var ParamInfo = /** @class */ (function () {
         this.type = rawParam.type.toString();
         this.defaultValue = rawParam.defaultValue;
         this.docText = rawParam.comment ? rawParam.comment.text : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
+        this.docText = this.docText.replace(/[\n\r]+/g, " ").trim();
         this.isOptional = rawParam.flags.isOptional;
         this.combined = this.name;
         if (this.isOptional)
@@ -59,14 +65,24 @@ var MethodSigInfo = /** @class */ (function () {
     function MethodSigInfo(rawSig) {
         var _this = this;
         this.name = rawSig.name;
-        this.docText = rawSig.hasComment() ? rawSig.comment.shortText + rawSig.comment.text : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
         this.returnType = rawSig.type ? rawSig.type.toString() : "";
-        this.isDeprecated = rawSig.comment && rawSig.comment.hasTag("deprecated");
+        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.");
+            this.returnDocText = rawSig.comment.returns;
+            this.returnDocText = this.returnDocText ? this.returnDocText.replace(/[\n\r]+/g, " ").trim() : "";
+            if (!this.returnDocText)
+                console.log("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.");
                 var param = new ParamInfo(rawParam);
                 _this.params.push(param);
                 paramStrings.push(param.combined);

lib/config/DocProcessor/tools/tsInfo.ts

@@ -21,7 +21,7 @@ import {
 import { CommentTag } from "typedoc/dist/lib/models";
 
 
-let libFolders = ["content-services"];//["core", "content-services", "process-services", "insights"];
+let libFolders = ["core", "content-services", "process-services", "insights"];
 let templateFolder = path.resolve(".", "config", "DocProcessor", "templates");
 
 let excludePatterns = [
@@ -38,6 +38,7 @@ let nameExceptions = {
 class PropInfo {
     name: string;
     type: string;
+    typeLink: string;
     defaultValue: string;
     docText: string;
     isInput: boolean;
@@ -47,18 +48,26 @@ class PropInfo {
     constructor(rawProp: DeclarationReflection) {
         this.name = rawProp.name;
         this.docText = rawProp.comment ? rawProp.comment.shortText : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
+        this.docText = this.docText.replace(/[\n\r]+/g, " ").trim();
         this.defaultValue = rawProp.defaultValue || "";
         this.defaultValue = this.defaultValue.replace(/\|/, "\\|");
         this.type = rawProp.type ? rawProp.type.toString() : "";
 
         if (rawProp.decorators) {
             rawProp.decorators.forEach(dec => {
-                if (dec.name === "Input")
+                if (dec.name === "Input") {
                     this.isInput = true;
 
-                if (dec.name === "Output")
+                    if (!this.docText)
+                        console.log(`Warning: Input "${rawProp.getFullName()}" has no doc text.`);
+                }
+
+                if (dec.name === "Output") {
                     this.isOutput = true;
+
+                    if (!this.docText)
+                        console.log(`Warning: Output "${rawProp.getFullName()}" has no doc text.`);
+                }
             });
         }
 
@@ -80,7 +89,7 @@ class ParamInfo {
         this.type = rawParam.type.toString();
         this.defaultValue = rawParam.defaultValue;
         this.docText = rawParam.comment ? rawParam.comment.text : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
+        this.docText = this.docText.replace(/[\n\r]+/g, " ").trim();
         this.isOptional = rawParam.flags.isOptional;
 
         this.combined = this.name;
@@ -100,22 +109,38 @@ class MethodSigInfo {
     name: string;
     docText: string;
     returnType: string;
+    returnDocText: string;
     signature: string;
     params: ParamInfo[];
     isDeprecated: boolean;
 
     constructor(rawSig: SignatureReflection) {
         this.name = rawSig.name;
-        this.docText = rawSig.hasComment() ? rawSig.comment.shortText + rawSig.comment.text : "";
-        this.docText = this.docText.replace(/[\n\r]+/g, " ");
         this.returnType = rawSig.type ? rawSig.type.toString() : "";
-        this.isDeprecated = rawSig.comment && rawSig.comment.hasTag("deprecated");
+
+        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.`);
+
+            this.returnDocText = rawSig.comment.returns;
+            this.returnDocText = this.returnDocText ? this.returnDocText.replace(/[\n\r]+/g, " ").trim() : "";
+            
+            if (!this.returnDocText)
+                console.log(`Warning: Return value of method "${rawSig.name}" has no doc text.`);
+            
+            this.isDeprecated = rawSig.comment.hasTag("deprecated");
+        }
 
         this.params = [];
         let paramStrings = [];
 
         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.`);
                 let param = new ParamInfo(rawParam);
                 this.params.push(param);
                 paramStrings.push(param.combined);

lib/package.json

@@ -122,6 +122,7 @@
     "karma-sourcemap-loader": "0.3.7",
     "karma-systemjs": "0.16.0",
     "karma-webpack": "2.0.9",
+    "liquidjs": "^3.1.1",
     "loader-utils": "1.1.0",
     "markdown-toc": "1.1.0",
     "markdownlint-cli": "^0.3.1",
@@ -155,6 +156,7 @@
     "tsickle": "^0.26.0",
     "tslint": "5.9.1",
     "tslint-loader": "3.5.3",
+    "typedoc": "^0.11.1",
     "typescript": "2.6.1",
     "uglifyjs-webpack-plugin": "1.1.6",
     "webpack": "3.10.0",