jsdoc: Visibility of constructors is handled wrong

I just noticed that the visibility of constructors (when using protoyping) seems to behave strangely. The main issue here seems to be that JSDoc does not permit classes without constructors, which can happen if the class is created internally (protected) but user’s should be permitted access to the members and methods of instances.

Example:

/**
 * Some description
 * @protected
 */
function AClass() {
    ...
}

/**
 * The method description
 * @public
 */
AClass.prototype.aMethod = function() {
    ...
}

When using jsdoc with -a public, the entire class AClass does not show up in the documentation, even though aMethod is declared as public.

Another example:

/**
 * @class AClass
 * @classdesc Some class description
 */

/**
 * Some description
 * @protected
 */
function AClass() {
    ...
}

Here, using -a public leads to the class being in the documentation, but the constructor is also documented, even though it is marked as protected.

About this issue

Original URL
State: closed
Created 9 years ago
Reactions: 8
Comments: 15 (4 by maintainers)

Commits related to this issue

add hideconstructor tag (#952) — committed to jsdoc/jsdoc by hegemonic 7 years ago
Merge tag '3.5.0' into esrijs-sdk-3.5.4 3.5.0 * tag '3.5.0': (97 commits) 3.5.0 bump revision; start 3.6.0-dev update 3.5.0 changelog 3.5.0 changelog reformat changelog add yields tag (#... — committed to bsvensson/jsdoc by lheberlie 7 years ago

Most upvoted comments

Fixed on master. JSDoc now supports a @hideconstructor tag, and if this tag is added to a class, the default template will not show the constructor. (Third-party templates will need to be updated to support this feature.)

The fix will be included in JSDoc 3.5.0.

hegemonic on Jul 7, 2017

Well, personally I think the problem is another. The fact that there is no (?) difference between a constructor and a class.

I find this to be the single biggest problem with JSDoc throughout all my projects and workplaces.

Any good documentation a class is decribed on a high level with some examples to get a grasp of the class in general. This should be able to include @examples and many other tags.

A constructor, is just one, of potentially several ways to create the object, and does not fit for having the responsibility to show the examples I mentioned above.

Ignoring that @class and @constructor currently is the same thing in JSDoc I would like to do something like this:

/**
* @class
* A good and long multi paragraph description of the Person.
* @example 
* // Use like this
* const p = new Person('Glenn', 'Jorde');
* @example 
* // Or this
* const p = new Person('Glenn Jorde');
*/
class Person {
  /**
  * @constructor
  * @param {String} first Specify first name, when second argument is missing this will be the full name
  * @param {String} [last=null] Last name.
  * @throws {ArgumentError} When missing `firstname`.
  */
  constructor(first, last=null) {
    if (arguments.length === 1) {
      this.name = first;
    } else {
      this.name = `${first} ${last}`;
    }
    // Input validation or something
  }
}

And these should render separately. And the data object between them should be easy to see what is what.

And as a bonus out of this solution there is no problem whatsoever to just omit the doclet with the @constructor to simply not show it in the documentation.

http://usejsdoc.org/howto-es2015-classes.html mentions how to document ES2015 classes, but the first doclet only supports a single line of text. Not a full doclet with examples etc. And yes, I’m sure this is possible to hack together with custom templates, but I really feel that this should be the default case.

Hopefully you understand what I mean. I typed it rather quickly.

tregusti on May 30, 2016

Just ran into same issue. Would be great to have a way to tell jsdoc not to display the constructor.

henridf on Dec 14, 2015

Hacker beware:

  <style>
    .ignore-this--this-is-here-to-hide-constructor,
    #TaskProperty { display: none }
  </style>

and s/TaskProperty/NameOfYourClass

machty on Feb 18, 2016