From 7d5f1b223bb7d86e83c815053b191bcd96b2f7b6 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Wed, 28 Mar 2018 16:00:59 +0100 Subject: [PATCH] [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 | 2 +- .../DocProcessor/templates/service.liquid | 4 +- lib/config/DocProcessor/tools/tsInfo.js | 32 ++++++++++---- lib/config/DocProcessor/tools/tsInfo.ts | 43 +++++++++++++++---- lib/package.json | 2 + 5 files changed, 63 insertions(+), 20 deletions(-) diff --git a/lib/config/DocProcessor/doctool.config.json b/lib/config/DocProcessor/doctool.config.json index ff5d36f910..6f7ef23478 100644 --- a/lib/config/DocProcessor/doctool.config.json +++ b/lib/config/DocProcessor/doctool.config.json @@ -1,5 +1,5 @@ { "enabledTools": [ - "tsInfo" + "index" ] } \ No newline at end of file diff --git a/lib/config/DocProcessor/templates/service.liquid b/lib/config/DocProcessor/templates/service.liquid index 3937893c11..193b3aee47 100644 --- a/lib/config/DocProcessor/templates/service.liquid +++ b/lib/config/DocProcessor/templates/service.liquid @@ -4,7 +4,7 @@ {% for meth in methods %}- `{{meth.name}}{{meth.signature}}: {{meth.returnType}}`
{{meth.docText}} - {% for param in meth.params %} - `{{param.combined}}` - {% if param.isOptional %}(Optional){% endif %}{{param.docText}} -{% endfor %} +{% for param in meth.params %} - `{{param.combined}}` - {% if param.isOptional %}(Optional){% endif %}{{param.docText}} +{% endfor %} - **Returns** `{{meth.returnType}}` - {{meth.returnDocText}} {% endfor %} {% endif %} \ No newline at end of file diff --git a/lib/config/DocProcessor/tools/tsInfo.js b/lib/config/DocProcessor/tools/tsInfo.js index 33141c4cff..a31d501094 100644 --- a/lib/config/DocProcessor/tools/tsInfo.js +++ b/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); diff --git a/lib/config/DocProcessor/tools/tsInfo.ts b/lib/config/DocProcessor/tools/tsInfo.ts index d1aa85d45d..56946589c4 100644 --- a/lib/config/DocProcessor/tools/tsInfo.ts +++ b/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); diff --git a/lib/package.json b/lib/package.json index d6e0438d6d..6e12eee1f1 100644 --- a/lib/package.json +++ b/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",