add hideconstructor tag (#952)

lib/jsdoc/schema.js

@@ -338,6 +338,10 @@ var DOCLET_SCHEMA = exports.DOCLET_SCHEMA = {
             type: BOOLEAN,
             optional: true
         },
+        hideconstructor: {
+            type: BOOLEAN,
+            optional: true
+        },
         ignore: {
             type: BOOLEAN,
             optional: true

lib/jsdoc/src/visitor.js

@@ -320,6 +320,9 @@ function makeConstructorFinisher(parser) {
         if ( (!parentDoclet.params || !parentDoclet.params.length) && doclet.params) {
             parentDoclet.params = doclet.params.slice(0);
         }
+        if (doclet.hideconstructor) {
+            parentDoclet.hideconstructor = doclet.hideconstructor;
+        }
 
         doclet.undocumented = true;
     };

lib/jsdoc/tag/dictionary/definitions.js

@@ -468,6 +468,12 @@ var baseTags = exports.baseTags = {
             delete doclet.memberof;
         }
     },
+    hideconstructor: {
+        mustNotHaveValue: true,
+        onTagged: function(doclet) {
+            doclet.hideconstructor = true;
+        }
+    },
     ignore: {
         mustNotHaveValue: true,
         onTagged: function(doclet) {

templates/default/tmpl/method.tmpl

@@ -2,7 +2,7 @@
 var data = obj;
 var self = this;
 ?>
-<?js if (data.kind !== 'module') { ?>
+<?js if (data.kind !== 'module' && !data.hideconstructor) { ?>
     <?js if (data.kind === 'class' && data.classdesc) { ?>
     <h2>Constructor</h2>
     <?js } ?>
@@ -15,7 +15,7 @@ var self = this;
     <?js } ?>
 <?js } ?>
 
-<?js if (data.kind !== 'module' && data.description) { ?>
+<?js if (data.kind !== 'module' && data.description && !data.hideconstructor) { ?>
 <div class="description">
     <?js= data.description ?>
 </div>

test/fixtures/hideconstructortag.js

@@ -0,0 +1,75 @@
+/**
+ * @classdesc Toaster singleton.
+ * @class
+ * @hideconstructor
+ */
+var Toaster = (function() {
+    var instance = null;
+
+    function Toaster() {}
+
+    /**
+     * Toast an item.
+     *
+     * @alias toast
+     * @memberof Toaster
+     * @instance
+     * @param {BreadyThing} item - The item to toast.
+     * @return {Toast} A toasted bready thing.
+     */
+    Toaster.prototype.toast = function(item) {};
+
+    return {
+        /**
+         * Get the Toaster instance.
+         *
+         * @alias Toaster.getInstance
+         * @returns {Toaster} The Toaster instance.
+         */
+        getInstance: function() {
+            if (instance === null) {
+                instance = new Toaster();
+                delete instance.constructor;
+            }
+
+            return instance;
+        }
+    };
+})();
+
+/**
+ * Waffle iron singleton.
+ */
+class WaffleIron {
+    #instance = null;
+
+    /**
+     * Create the waffle iron.
+     *
+     * @hideconstructor
+     */
+    constructor() {
+        if (#instance) {
+            return #instance;
+        }
+
+        /**
+         * Cook a waffle.
+         *
+         * @param {Batter} batter - The waffle batter.
+         * @return {Waffle} The cooked waffle.
+         */
+        this.cook = function(batter) {};
+
+        this.#instance = this;
+    }
+
+    /**
+     * Get the WaffleIron instance.
+     *
+     * @return {WaffleIron} The WaffleIron instance.
+     */
+    getInstance() {
+        return new WaffleIron();
+    }
+}

test/specs/tags/hideconstructortag.js

@@ -0,0 +1,16 @@
+'use strict';
+
+describe('@hideconstructor tag', function() {
+    var docSet = jasmine.getDocSetFromFile('test/fixtures/hideconstructortag.js');
+    var toaster = docSet.getByLongname('Toaster')[0];
+    var waffleIron = docSet.getByLongname('WaffleIron')[0];
+
+    it('should add a `hideconstructor` attribute to pre-ES2015 classes', function() {
+        expect(toaster.hideconstructor).toBe(true);
+    });
+
+    it('should add a `hideconstructor` attribute to ES2015 classes when the constructor is tagged',
+        function() {
+            expect(waffleIron.hideconstructor).toBe(true);
+        });
+});