Normal comments should not be included in the documentation

[BobVul]

There are some cases where I would like to add normal (non-doc) JS comments. Unfortunately, it seems like jsduck picks up these comments, particularly when they are immediately above an overriding member.

Example:

/**
 * Some class Foo
 */
Ext.define('Foo', {
    /**
     * x doc-comment
     */
    x: false
});

/**
 * Some class Foo.Bar
 */
Ext.define('Foo.Bar', {
    extend: 'Foo',

    // internal x comment
    x: true
});

I would expect the non-doc-comment to not appear in the documentation.

[nene]

This is partly by design.

The reason for picking up these normal comments is to include some docs also for private members. By convention doc-comments mark the member as public, so picking up line-comments allows an easy way to pick up private member docs without having to use @private tag. The docs would usually be hidden along with private members themselves.

The member x is already declared public in superclass, so the line-comment ends up in public member documentation. That's indeed a questionable behavior.

I think JSDuck should require public members to always be documented with doc-comments if one wants to include text to the documentation. There's one slight problem though: when you change the superclass member to private, the docs from subclass will suddenly start overriding the docs. That seems like a negligible thing though - one usually doesn't care much about private member docs.

As a workaround you can suppress this by adding @ignore to the comment:

    // @ignore internal x comment
    x: true

This would however also ignore the new default value. To preserve that, you could explicitly say that the docs will come from parent:

    // @ignore internal x comment
    /** @inheritdoc */
    x: true

[BobVul]

Explicitly specifying a doc-comment seems to work, thanks.

The current behaviour is a tad unintuitive, though: I don't expect non-doc-comments to be included in the docs - if something is to be publicly documented, then that should be made explicit through the use of a doc-comment.