Constructor generation with documentation.

From [PR#74](englercj#74) with fix.
alxroyer · Sep 6, 2019 · 82e01e4 · 82e01e4
1 parent 1cefe92
commit 82e01e4
Show file tree

Hide file tree

Showing 5 changed files with 91 additions and 42 deletions.
diff --git a/src/Emitter.ts b/src/Emitter.ts
@@ -51,22 +51,31 @@ function isExportDefault(doclet: TDoclet)
 
 function shouldMoveOutOfClass(doclet: TDoclet)
 {
-    if (isConstructor(doclet))
-    {
-        return false;
-    }
-    else
-    {
-        return isClassLike(doclet)
-            || isModuleLike(doclet)
-            || isEnum(doclet)
-            || doclet.kind === 'typedef';
-    }
+    return isClassLike(doclet)
+        || isModuleLike(doclet)
+        || isEnum(doclet)
+        || doclet.kind === 'typedef';
+}
+
+function isClassDeclaration(doclet: TDoclet)
+{
+    return (
+        doclet && (doclet.kind === 'class')
+        && doclet.meta && (
+            // When the owner class's comment contains a @class tag, the first doclet for the class is detached one,
+            // btw the 'code' section is empty.
+            (! doclet.meta.code.type)
+            || (doclet.meta.code.type === 'ClassDeclaration')
+        )
+    );
 }
 
 function isConstructor(doclet: TDoclet)
 {
-    return doclet.kind === "class" && doclet.name === doclet.memberof
+    return (
+        (doclet.kind === 'class')
+        && doclet.meta && (doclet.meta.code.type === 'MethodDefinition')
+    );
 }
 
 export class Emitter
@@ -158,6 +167,26 @@ export class Emitter
         {
             const doclet = docs[i];
 
+            if ((doclet.kind !== 'package') && isConstructor(doclet))
+            {
+                // If this doclet is a constructor, do not watch the 'memberof' attribute,
+                // it usually has the same value as the owner class's declaration,
+                // it does point the owner class itself.
+                // Use the 'longname' which equals the owner class's 'longname'.
+                const ownerClass = this._treeNodes[doclet.longname];
+                if ((!ownerClass) || (!isClassDeclaration(ownerClass.doclet)))
+                {
+                    warn(`Failed to find owner class of constructor '${doclet.longname}'.`, doclet);
+                    continue;
+                }
+                debug(`Emitter._buildTree(): adding constructor ${docletDebugInfo(doclet)} to class declaration ${docletDebugInfo(ownerClass.doclet)}`);
+                ownerClass.children.push({ doclet: doclet, children: [] });
+                continue;
+
+                // Note: The constructor should be generated with its documentation whatever its access level.
+                // Do not move this block after the test below.
+            }
+
             if (doclet.kind === 'package' || this._ignoreDoclet(doclet))
             {
                 debug(`Emitter._buildTree(): skipping ${docletDebugInfo(doclet) } (package or ignored)`, doclet);
@@ -380,10 +409,17 @@ export class Emitter
 
     private _ignoreDoclet(doclet: TAnyDoclet): boolean
     {
-        if (doclet.kind === 'package'
-            || doclet.ignore
-            || (!this.options.private && doclet.access === 'private')) {
-            debug(`Emitter._ignoreDoclet(doclet=${docletDebugInfo(doclet)}) => true (package, ignored or private disabled)`);
+        let reason: string|undefined = undefined;
+        if (doclet.kind === 'package')
+            reason = 'package doclet';
+        else if (!!doclet.ignore)
+            reason = 'doclet with an ignore flag';
+        else if (!this.options.private && doclet.access === 'private')
+            reason = 'private access disabled';
+        if (reason
+            || (doclet.kind === 'package')) // <= hack for typescript resolutions
+        {
+            debug(`Emitter._ignoreDoclet(doclet=${docletDebugInfo(doclet)}) => true (${reason})`);
             return true
         }
 

diff --git a/src/create_helpers.ts b/src/create_helpers.ts
@@ -108,16 +108,19 @@ export function createClass(doclet: IClassDoclet, children?: ts.Node[]): ts.Clas
 
     if (doclet.params)
     {
-        const params = createFunctionParams(doclet);
-
-        members.unshift(
-            ts.createConstructor(
-                undefined,  // decorators
-                undefined,  // modifiers
-                params,     // parameters
-                undefined   // body
-            )
-        );
+        // Check whether the constructor has already been declared.
+        if (members.filter(member => ts.isConstructorDeclaration(member)).length === 0)
+        {
+            debug(`createClass(${docletDebugInfo(doclet)}): no constructor set yet, adding one automatically`);
+            members.unshift(
+                ts.createConstructor(
+                    undefined,                      // decorators
+                    undefined,                      // modifiers
+                    createFunctionParams(doclet),   // parameters
+                    undefined                       // body
+                )
+            );
+        }
     }
 
     if (doclet.properties)
@@ -346,12 +349,11 @@ export function createConstructor(doclet: IClassDoclet): ts.ConstructorDeclarati
 {
     debug(`createConstructor(${docletDebugInfo(doclet)})`);
 
-    const params = createFunctionParams(doclet);
     return handleComment(doclet, ts.createConstructor(
-        undefined,  // decorators
-        getAccessModifiers(doclet),  // modifiers
-        params,     // parameters
-        undefined   // body
+        undefined,                      // decorators
+        getAccessModifiers(doclet),     // modifiers
+        createFunctionParams(doclet),   // parameters
+        undefined                       // body
     ))
 }
 

diff --git a/src/publish.ts b/src/publish.ts
@@ -10,30 +10,39 @@ import { setVerbose, setDebug, debug, docletDebugInfo } from './logger';
  */
 export function publish(data: TDocletDb, opts: ITemplateConfig)
 {
-    // start with taking into account 'verbose' and 'debug' options
+    // Start with taking into account 'verbose' and 'debug' options.
     setVerbose(!!opts.verbose);
     setDebug(!!opts.debug);
 
-    // in order not to break backward compatibility, the 'documented' generation strategy is used by default
+    // In order not to break backward compatibility, the 'documented' generation strategy is used by default.
     if (! opts.generationStrategy)
     {
         opts.generationStrategy = 'documented';
     }
     debug(`publish(): Generation strategy: '${opts.generationStrategy}'`);
 
-    // do not remove undocumented doclet with the 'exported' generation strategy
-    // the Emitter._walkExportedDoclets() function will make the appropriate selection later
+    // Do not remove undocumented doclet with the 'exported' generation strategy.
+    // The Emitter._walkExportedDoclets() function will make the appropriate selection later.
     if (opts.generationStrategy !== 'exported')
     {
         // remove undocumented stuff.
         data(
-            // use of a function as the TaffyDB query in order to track what is removed
+            // Use of a function as the TaffyDB query in order to track what is removed.
             // see [TaffyDB documentation](http://taffydb.com/writing_queries.html)
             function(this: TDoclet) // <= 'this' type declaration inspired from [stackoverflow](https://stackoverflow.com/questions/41944650)
             {
                 if (this.undocumented)
                 {
-                    debug(`publish(): ${docletDebugInfo(this)} removed`);
+                    // Some doclets are marked 'undocumented', but actually have a 'comment' set.
+                    if ((! this.comment) || (this.comment === ''))
+                    {
+                        debug(`publish(): ${docletDebugInfo(this)} removed`);
+                        return true;
+                    }
+                    else
+                    {
+                        debug(`publish(): ${docletDebugInfo(this)} saved from removal`);
+                    }
                 }
                 return false;
             }

diff --git a/test/expected/class_all.d.ts b/test/expected/class_all.d.ts
@@ -132,7 +132,12 @@ declare module "util" {
      * @mixes Things
      */
     class MyThing extends OtherThing implements Stuff, Things {
-        constructor(...a: number[]);
+        /**
+         * Constructs!
+         * @param {...number} a - The number.
+         * @private
+         */
+        private constructor(...a: number[]);
         /**
          * Derp or something.
          *

diff --git a/test/expected/constructors.d.ts b/test/expected/constructors.d.ts
@@ -2,7 +2,6 @@
  * Class documentation.
  */
 declare class MyClass {
-
     /**
      * Constructor documentation.
      * @public
@@ -16,7 +15,6 @@ declare class MyClass {
  * Class documentation.
  */
 declare class MyClass2 {
-
     /**
      * Constructor documentation.
      * @protected
@@ -30,7 +28,6 @@ declare class MyClass2 {
  * Class documentation.
  */
 declare class MyClass3 {
-
     /**
      * Constructor documentation.
      * @package
@@ -44,7 +41,6 @@ declare class MyClass3 {
  * Class documentation.
  */
 declare class MyClass4 {
-
     /**
      * Constructor documentation.
      * @private
@@ -53,3 +49,4 @@ declare class MyClass4 {
      */
     private constructor(a: number, b: string);
 }
+