search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Documented members of @ignored/@private functions with @constructor produce warnings #248

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
'What steps will reproduce the problem?'
(run JsDoc Toolkit on the following)

/**
 * @private
 * @constructor
 */
function Foo() {

    /**
     * Runs bar!
     */
    this.bar = function() {

    };
}

(this also happens with @ignore instead of @private)

'What is the expected output? What do you see instead?'

Well, I had hoped it would hit the @ignore/@private alongside an
@constructor would indicate that the whole class should be skipped.
Basically my real case is one where I have a nested class:

ex:
function A() {

    /**
     * @ignore
     * @constructor
     */
    function B() {
        /** @type String */
        this.foo = "foo";
    }
}

and I think the inner class should be ignored completely when the toolkit
is run without the private options. Instead, the toolkit issues a warning
that it cannot find the parent symbol for which to document a particular
sub-symbol (meaning it applied the @ignore/@private to that function only
and kept on reading/parsing).

'What version of the product are you using? On what operating system?'
Version 2.3.0

Original issue reported on code.google.com by mcbain....@gmail.com on 3 Sep 2009 at 8:16

GoogleCodeExporter commented 9 years ago 
This behavior was a design decision, with the intention of causing the least 
pain (it can be a painful issue). 
There are two ways to go when confronted with an ignored (or private) class: 
either A) we always ignore all the 
members (what you are proposing), or B) we never ignore any of the members (as 
it is implemented).

The reason A lost and B won that contest was that in the case of B you always 
have the option of selectively 
adding @ignore tags to any or all members to achieve precisely what you want. 
In the case of A you might 
want to "not ignore" some members, and then what do you do? B wins by being 
more flexible.

However if you really do want to just ignore everything doc in a section of 
code you do have the option of 
using a metatag, like so:

/**#@+
    @private
 */

/**
 * @constructor
 */
function Foo() {

    /**
     * Runs bar!
     */
    this.bar = function() {

    };
}

/**#@-*/

/**
 * @constructor
 */
function Baz() {
}

That makes Foo and Foo#bar private, whilst Baz is not private. This is 
explained further here:

http://code.google.com/p/jsdoc-toolkit/wiki/MetaTags

Original comment by micmath on 12 Sep 2009 at 5:59