swallowzhang / jsdoc-toolkit

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

@exports does not export to another symbol's prototype properly #331

Open GoogleCodeExporter opened 8 years ago

GoogleCodeExporter commented 8 years ago
What steps will reproduce the problem?
1. @exports a variable to a prototype of another symbol.

What is the expected output? What do you see instead?
 It should document items assigned to properties on that exported variable as if they were part of the prototype. Instead, JsDoc Toolkit complains that the prototype hasn't been documented yet.

What version of the product are you using? On what operating system?
2.4.0

Please provide any additional information below.

/**
 * @namespace
 */
var App = {};

/**
 * @namespace
 */
var App = {};

(function ()
{
    /**
     * @exports testing as App.Testing
     */
    var testing =
    /**
     * @class
     */
    App.Testing = function ()
    {
    };

    /**
     * This function will be documented.
     */
    testing.prototype.testingf = function ()
    {
    };
}());

(function ()
{
    /**
     * @exports test as App.Test.prototype
     */
    var test =
    /**
     * @class
     */
    App.Test = function ()
    {
    };
    test = test.prototype;

    /**
     * This function's documentation will be dropped on the floor.
     */
    test.testf = function ()
    {
    };
}());

>> WARNING: Trying to document testf as a member of undocumented symbol 
App.Test.prototype.
1 warning.

Original issue reported on code.google.com by mcbain....@gmail.com on 6 Jan 2012 at 12:35

GoogleCodeExporter commented 8 years ago
I tooled around a bit, and not quite by dumb luck I landed upon a spot that let 
me make a quick-fix to get what I wanted above inside of 
JSDOC.Parser.addSymbol(symbol) at line 19.

The gist of my fix is to normalize a match replacement's prototypes to "#" and 
remove the following dot. Currently it can match if you use "#" instead of 
".prototype" in an @exports declaration, but the dot left behind prevents JsDoc 
Toolkit from finding a documented symbol afterwards (ex: test.testf -> 
App.Test#.testf).

        replacement = JSDOC.Parser.rename[n].replace(/\.prototype(?:\.|$)/g, "#");
        if (/#$/.test(replacement)) {
            n += ".";
        }

The non-capturing group part should ensure anything only starting with 
prototype doesn't get mistakenly replaced. All the following calls to 
symbol.alias.replace(*) use the variable "replacement".

This allows my previous example to be documented without any warnings and with 
what appears to be correct output. It also allows the following, if you happen 
to have such interesting code:

/**
 * @namespace
 */
var App = {};

(function ()
{
    /**
     * @class
     */
    App.Test = function ()
    {
    };
    /**
     * @exports test as App.Test.prototype.Bar
     */
    var test =
    /**
     * @namespace
     */
    App.Test.prototype.Bar = {};

    /**
     * This is a function on a namespace called "Bar" that only exists on instances of App.Test. It will show up as App.Test#Bar.testf in the documentation.
     */
    test.testf = function ()
    {
    };
}());

Original comment by mcbain....@gmail.com on 6 Jan 2012 at 2:04

GoogleCodeExporter commented 8 years ago
'All the following calls to ...' -> 'The following calls to 
symbol.name.replace(*) and symbol.alias.replace(*) use the variable 
"replacement".'

Original comment by mcbain....@gmail.com on 6 Jan 2012 at 2:07

GoogleCodeExporter commented 8 years ago
Forgot to add that I declared the variable "replacement" in the fixed code 
mentioned above here:

if (JSDOC.Parser.rename) {
    var replacement;

which is only a few lines up from the fix itself.

Original comment by mcbain....@gmail.com on 25 Jan 2012 at 1:03