Merge pull request #130 from webdoc-labs/feature/lang-ts-parameter-pr…

…operty

Add support for TypeScript parameter properties

example/src/Car.ts

@@ -82,6 +82,12 @@ export class Car extends PhysicalObject {
    */
   static DEFAULT_DRIVE_SHIFT = "manual"
 
+  /**
+   */
+  constructor(public model: string = "TEST") {
+    super();
+  }
+
   /**
    * @member {number}
    */

packages/webdoc-parser/.flowconfig

@@ -1,6 +1,8 @@
 [ignore]
+./lib
 
 [include]
+./src
 
 [libs]
 

packages/webdoc-parser/src/symbols-babel/build-symbol-tree.js

@@ -27,6 +27,7 @@ import {
   isObjectPattern,
   isRestElement,
   isScope,
+  isTSParameterProperty,
   isVariableDeclaration,
 } from "@babel/types";
 import {
@@ -295,7 +296,14 @@ function captureSymbols(nodePath: NodePath, parent: Symbol): ?Symbol {
 
   // leadingComments -> documented
   // isScope -> children may be documented even if node is not
-  if (leadingComments.length || isScope(node) || reportUndocumented) {
+  // TSParameterProperty -> They don't have doc-comments but the @param tag for the parameter
+  //  covers it so we always include them.
+  if (
+    leadingComments.length ||
+    isScope(node) ||
+    isTSParameterProperty(node) ||
+    reportUndocumented
+  ) {
     if (!initComment && leadingComments.length && simpleName) {
       nodeDocIndex = SymbolUtils.commentIndex(leadingComments);
     }
@@ -304,6 +312,10 @@ function captureSymbols(nodePath: NodePath, parent: Symbol): ?Symbol {
 
     if (!comment) {
       nodeSymbol.meta.undocumented = true;
+
+      if (isTSParameterProperty(node)) {
+        nodeSymbol.meta.undocumentedAnchored = true;
+      }
     }
 
     // Does user want to document as a property? Then remove VIRTUAL flag
@@ -320,7 +332,11 @@ function captureSymbols(nodePath: NodePath, parent: Symbol): ?Symbol {
         path: [...parent.path, simpleName],
         comment,
         members: [],
-        loc: _createLoc(nodeDoc ? nodeDoc.loc : null),
+        loc: _createLoc(
+          nodeDoc ? nodeDoc.loc :
+            node.loc ? node.loc : // Needed for undocumented symbols
+              null,
+        ),
       }, nodeSymbol);
 
       nodeSymbol = SymbolUtils.addChild(nodeSymbol, parent);

packages/webdoc-parser/src/symbols-babel/extract-metadata.js

@@ -67,6 +67,7 @@ import {
   isTSNullKeyword,
   isTSNumberKeyword,
   isTSObjectKeyword,
+  isTSParameterProperty,
   isTSParenthesizedType,
   isTSPropertySignature,
   isTSQualifiedName,
@@ -191,10 +192,13 @@ export function extractParams(
   const params: Param[] = [];
 
   for (let i = 0; i < nodeParams.length; i++) {
-    const paramNode = nodeParams[i];
-
+    let paramNode = nodeParams[i];
     let param: ?$Shape<Param>;
 
+    if (isTSParameterProperty(paramNode)) {
+      paramNode = paramNode.parameter;
+    }
+
     // TODO: Infer types
     if (isIdentifier(paramNode)) {
       param = {
@@ -208,10 +212,12 @@ export function extractParams(
         variadic: true,
       };
     } else if (isAssignmentPattern(paramNode)) {
+      const extraRaw = paramNode.right.extra && paramNode.right.extra.raw;
+
       param = {
         identifier: paramNode.left.name,
         optional: paramNode.optional || false,
-        default: paramNode.right.raw,
+        default: paramNode.right.raw || extraRaw,
       };
     } else if (isObjectExpression(paramNode)) {
       // TODO: Find a way to document {x, y, z} parameters

packages/webdoc-parser/src/symbols-babel/extract-symbol.js

@@ -13,6 +13,7 @@ import {
   type VariableDeclarator,
   isArrowFunctionExpression,
   isAssignmentExpression,
+  isAssignmentPattern,
   isBooleanLiteral,
   isCallExpression,
   isClassDeclaration,
@@ -23,6 +24,7 @@ import {
   isExpressionStatement,
   isFunctionDeclaration,
   isFunctionExpression,
+  isIdentifier,
   isInterfaceDeclaration,
   isLiteral,
   isMemberExpression,
@@ -39,6 +41,7 @@ import {
   isTSEnumMember,
   isTSInterfaceDeclaration,
   isTSMethodSignature,
+  isTSParameterProperty,
   isTSPropertySignature,
   isTSTypeElement,
   isThisExpression,
@@ -125,6 +128,31 @@ export default function extractSymbol(
         nodeSymbol.meta.dataType = dataType;
       }
     }
+  } else if (isTSParameterProperty(node)) {
+    // Example:
+    // constructor(private readonly param: Type) {}
+
+    const parameter = node.parameter;
+
+    if (isIdentifier(parameter)) {
+      name = parameter.name;
+    } else if (isAssignmentPattern(parameter)) {
+      name = parameter.left.name;
+      nodeSymbol.meta.defaultValue = parameter.right.raw ||
+        (parameter.right.extra && parameter.right.extra.raw);
+    }
+
+    nodeSymbol.meta.access = node.accessibility;
+    nodeSymbol.meta.object = "this";// Assembly-mods will resolve to the parent class symbol
+    nodeSymbol.meta.readonly = node.readonly;
+    nodeSymbol.meta.scope = "instance";
+    nodeSymbol.meta.type = "PropertyDoc";
+
+    if (parameter.typeAnnotation) {
+      nodeSymbol.meta.dataType = extractType(parameter.typeAnnotation);
+    }
+
+    flags |= OBLIGATE_LEAF;
   } else if (isClassDeclaration(node) || isClassExpression(node)) {
     // Example:
     // class ClassName {}

packages/webdoc-parser/src/transformer/mod-prune.js

@@ -4,17 +4,31 @@ import type {Doc, RootDoc} from "@webdoc/types";
 import {removeChildDoc} from "@webdoc/model";
 
 export default function prune(doc: Doc, root: RootDoc) {
+  let anchoredChildren = 0;
+
   if (doc.tags && doc.tags.find((tag) => tag.name === "ignore")) {
     removeChildDoc(doc);
     return;
   } else {
     for (let i = 0; i < doc.members.length; i++) {
-      prune(doc.members[i], root);
+      const member = doc.members[i];
+
+      prune(member, root);
+
+      if (member.parserOpts && member.parserOpts.undocumentedAnchored) {
+        anchoredChildren++;
+      }
     }
   }
 
-  // Prune undocumented docs with no children too
-  if (doc.parserOpts && doc.parserOpts.undocumented && doc.members.length === 0) {
+  // Prune undocumented docs with no children too OR only anchored children.
+  // (anchored children _can_ be pruned but are not if any ancestor is retained)
+  if (
+    doc.parserOpts &&
+    doc.parserOpts.undocumented &&
+    !doc.parserOpts.undocumentedAnchored &&
+    doc.members.length === anchoredChildren
+  ) {
     removeChildDoc(doc);
   }
   if (doc.type !== "PropertyDoc" && doc.type !== "MethodDoc" && doc.type !== "FunctionDoc") {

packages/webdoc-parser/src/transformer/symbol-to-doc.js

@@ -147,6 +147,7 @@ export default function symbolToDoc(symbol: Symbol): ?Doc {
   options.parserOpts = {
     object: symbol.meta.object,
     undocumented: symbol.meta.undocumented,
+    undocumentedAnchored: symbol.meta.undocumentedAnchored,
   };
 
   const tags: Tag[] = [];

packages/webdoc-parser/src/types/Symbol.js

@@ -36,7 +36,8 @@ export type SymbolSignature = {
   value?: ?string,
   type?: ?DocType,
   typeParameters?: ?Array<string>,
-  undocumented?: boolean
+  undocumented?: boolean,
+  undocumentedAnchored?: boolean, // Prevent pruning of symbol if parent is retained
 }
 
 // The location of a symbol

packages/webdoc-parser/test/parse-ts.js

@@ -55,4 +55,56 @@ describe("@webdoc/parser.parse (Typescript)", function() {
     expect(methodDoc.access).to.equal("protected");
     expect(methodDoc.returns[0].dataType[0]).to.equal("void");
   });
+
+  it("should work with property parameters", async function() {
+    const documentTree = await parse([{
+      content: `
+        class RedBlackTree {
+          /** HERE */
+          constructor(protected readonly root: Node) {}
+        }
+      `,
+      path: ".ts",
+      package: createPackageDoc(),
+    }]);
+
+    const rootProperty = findDoc("RedBlackTree.root", documentTree);
+    const ctor = findDoc("RedBlackTree.constructor", documentTree);
+
+    expect(rootProperty).to.not.equal(null);
+    expect(rootProperty.access).to.equal("protected");
+    expect(rootProperty.dataType[0]).to.equal("Node");
+    expect(rootProperty.name).to.equal("root");
+    expect(rootProperty.readonly).to.equal(true);
+
+    expect(ctor).to.not.equal(null);
+    expect(ctor.params.length).to.equal(1);
+
+    const rootParameter = ctor.params[0];
+
+    expect(rootParameter.dataType[0]).to.equal("Node");
+    expect(rootParameter.identifier).to.equal("root");
+  });
+
+  it("should work with property parameter when default values are assigned", async function() {
+    const documentTree = await parse([{
+      content: `
+        class AVLTree {
+          /** HERE */
+          constructor(protected root: Node = "null") {}
+        }
+      `,
+      path: ".ts",
+      package: createPackageDoc(),
+    }]);
+
+    const rootProperty = findDoc("AVLTree.root", documentTree);
+    const ctor = findDoc("AVLTree.constructor", documentTree);
+
+    expect(rootProperty).to.not.equal(null);
+    expect(ctor).to.not.equal(null);
+
+    expect(rootProperty.defaultValue).to.equal("\"null\"");
+    expect(ctor.params[0].default).to.equal("\"null\"");
+  });
 });

packages/webdoc-types/index.js.flow

@@ -10,7 +10,8 @@ export type SourceFile = {
 export type ParserOpts = {
   memberof?: string[],
   object?: string,
-  undocumented?: boolean
+  undocumented?: boolean,
+  undocumentedAnchored?: boolean
 };
 
 export type Param = {