stephanieerin / jsdoc-toolkit Goto Github PK

What version of the product are you using? On what operating system?
1.3.2 on Vista 64-bit

Please provide any additional information below.
It would be nice if the program could output a one line message before
exiting that indicates the number of warnings/errors that were encountered.
 We would then know whether we need to search the log for any issues.

If you have a jsdoc section start like this, the output includes the asterisks.

Is this intentional?

/** *********************
 * @constructor
 */
function Document(file)
{
    var strFile = file ? file : null;
    /**
     * @method open
     */
    function Document_open()
    {
        if(!strFile)
        {
            // Access private variable
            print("Open: ["+strFile+"]\n");
        }
        else
        {
            print("File not defined: ["+strFile+"]\n");
        }
        return undefined;
    }
    this.open = Document_open();
    return this;
}

What steps will reproduce the problem?

BlaBlaBla.prototype = {
    toString: function() {
    }
}

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

toString should appear in the output but doesn't.

What steps will reproduce the problem?
1. Define a constructor
2. Define a method for constructor, method name beginning with "_"
3. Create documentation with -a cmdline parameter

What is the expected output? What do you see instead?
- expected: no method in constructor class
- instead see: the method is shown in method summary/detail

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

Please provide any additional information below.
--

It doesn't get the comment for the method.

However if you put the doc tags near the 'this.open = Document_open' it works.

/**
 * @constructor
 */
function Document(file)
{
    var strFile = file ? file : null;
    /**
     * @method open
     */
    function Document_open()
    {
        if(!strFile)
        {
            // Access private variable
            print("Open: ["+strFile+"]\n");
        }
        else
        {
            print("File not defined: ["+strFile+"]\n");
        }
        return undefined;
    }
    this.open = Document_open();
    return this;
}

Here is a quick change for the "sunny" template set that limits the
descriptions within the summary sections to just the first sentence.  This
is more like JavaDoc.

Since I cannot seem to supply a file without getting a server error, I just
added the following to each "desc" output in the summary tables:

.replace(/(\w*\.) .*/,"$1")

So, in the case of the METHOD SUMMARY table, I modified {+method.desc+} to
be {+method.desc.replace(/(\w*\.) .*/,"$1")+}

[deleted issue]

@returns tag should be synonym for @return tag

What steps will reproduce the problem?
1. set @scope of an object literal to foo.prototype
2. set object literal to { bar: function(){}}

    /** @scope foo.prototype */
    {
        /**
         * Does something.
         */
        bar : function (one, two) {
        }
    }

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

bar() should be a memberof foo, but instead we get foo.prototype.bar() as a
static function.

What steps will reproduce the problem?
1. label a symbol with the tag: @extends Someother

What is the expected output? 
Either:
1. any methods and properties of Someother appear to be methods and
properties of the current symbol.
2. a simple link is provided to the docs for Someother.

v 1.2.1

Modified two files to fix.

[deleted issue]

Attached is two objects.

1) LOGGER (prototypal)
2) LOGGER2 (parasitic)

The output should group by:
 1) object
    a) fields/properties
    b) methods/objects
 2) object instance
    a) constructor(s)
    b) fields/properties
    c) methods/objects

Currently:
 1) constructors
 2) methods/functions
 3) fields/properties

If this is just a matter of modifying a template, then don't worry about it.

What steps will reproduce the problem?
1. Run JsDoc (app/run.js)

When I ran JsDoc 1.0.1 preview, the JVM errored out and referred me to
JsIO.js line 93, stating that there was no "ls" function.  I changed the
call from Util.ls(...) to IO.ls(...) and the error was fixed.

What steps will reproduce the problem?
1. Add a @class tag to a constructor
2. add a description to that tag

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

The description associated with the @class tag should appear as the
description of that constructor. At the moment is is simply ignored. It
would be a convenient enhancement if this was appended onto the constructor
description, as it would increase backwards compatibility with older
JsDoc.pm comments.

For example:

/**
 * Call this constructor to make a new myCoolClass
 * @constructor
 * @class
 * Blah blah blah
 */
myCoolClass = function()
{
};

Note that in scriptDoc the same tag is: @classDescription

What steps will reproduce the problem?
1. Comment a prototype assignment
/** <p>Set an Array as the prototype object</p> */
SarissaNodeList.prototype = new Array(0);

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

This isn't a valid doc comment, the comment should be on the function
declaration. The doc comment on the prototype should be ignored by JsDoc
Toolkit.

[deleted issue]

As we spoke about it, i paste it the post.

Thanks in advance

Regards Alex


Michael : 
I understand your example but it seems a little inflexible to me. What would
the comment look like if the config parameter were named "blah" instead of
"config"? What if there were other, normal parameters expected as well? What
if there were two (or more) config objects? Why couldn't this tag be used on
functions that were not constructors?

Suggested answer to my own questions....

/**
* @constructor
* @param blah The configuration object.
* @config _a {Integer} number of apples
* @param blah2 Another configuration object.
* @config _b {Integer} number of bananas
* @param etc An ordinary parameter.
*/

where blah = { _a:10 }; blah = { _b:100 }; etc = "ok";

Using this syntax your previous example would work, but it's flexible enough
to work with my example too.

Your thoughts? 

Alex:
So, you are meaning that for one tag param it could be 1 and more tag
config in order to have many config object?

It's great, so we can have config object for function and not only
constructors.

OK.

So you will append a new section for constructor or methods which have
a config object.

I think it's a good idea 

It would be great to have support for an @event tag to create an events
section in the documentation.

Code Example:
http://developer.yahoo.com/yui/docs/DataSource.js.html

Output Example
http://developer.yahoo.com/yui/docs/YAHOO.util.DataSource.html

What steps will reproduce the problem?
1. Generate documentation with the Sunny template for the following code:

/**
  * This is a Chart class.
  * @name Chart
  * @class
  */

framework.createClass(
    "Chart",
    /** @scope Chart.prototype */
    {
        /** Gets the bounding rectangle of the chart's graph area where
            the coordinates are displayed. This area is expressed
            relative to the root chart div, which also contains the
            chart and axis labels.
            @return {Rectangle} The bounding <code>Rectangle</code>.
        */
        getClientRect: function(container, args) {
        }
    }
);

What is the expected output? What do you see instead?
In the method summary, only the first sentence should be displayed: "Gets
the bounding rectangle of the chart's graph area where the coordinates are
displayed."

However, in the output, part of the second sentence is also displayed in
the summary: "Gets the bounding rectangle of the chart's graph area where
the coordinates are displayed. relative to the root chart div, which also
contains the chart and axis labels."

I tried adding a third sentence, and it got added to the summary as well.

What version of the product are you using? On what operating system?
1.3.2.  I just downloaded and tried this new version.  I verified that the
bug still exists.

Command line parameter to specify additional extensions.

What steps will reproduce the problem?
1. generate doc from different (sub)folders with param -r
2. no folder-hierarchie in left frame
3.

What is the expected output? What do you see instead?
The left menu frame shows list of links to documentation of each .js-file
I expect kind of tree-view of links to documentation

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

Please provide any additional information below.
ex. 
Folder "prog1" contains files init.js and prog1.js
Folder "prog2" contains files init.js and prog2.js

Currently I will get this in left navigation:

init.js
prog1.js
init.js
prog2.js

I should expect a hierarchie like

prog1
> init.js
> prog1.js

prog2
> init.js
> prog2.js


Thanks.

We plan on using the same template on a number of projects and we wanted to
be able to pass information into the parser to be displayed in the title
and on the splash page. Example tags: SVN reversion number, Project name,
creation date, user who updated.

So we added a -D = "Define" tag to the commandline interface and can accept
as many as needed, they can then be used on any template parsed from
{+TAGS.mytag+}.

usages -D="mykey:myvalue" -D="myprj:thisprj"

Example:

java -jar app/js.jar app/run.js -t=templates/spicey -r=2 -a /my/source/
-d=/my/docs -D="project:Testing Project" -D="REV:1095" -D="GENDATE:09-21-07"

this will gibe you {+TAGS.project+}, {+TAGS.REV+} and (+TAGS.GENDATE+} in
any template.

Hope this helps 

Vince

This should read in a JSON file to set values for the commandline options.

Looks like when an explicit file path list is passed, the files cannot be
found without adding an -r option. E.g. this wont work:

/Users/manos/workspace/sarissa/target/jsdoc_run/jsdoc_toolkit-1.3.1/app/run.js
   -d=/Users/manos/workspace/sarissa/target/site//jsdoc 
/Users/manos/workspace/sarissa/src/main/js/gr/abiss/js/sarissa/sarissa.js
/Users/manos/workspace/sarissa/src/main/js/gr/abiss/js/sarissa/sarissa_ieemu_xpa
th.js


but this will:



/Users/manos/workspace/sarissa/target/jsdoc_run/jsdoc_toolkit-1.3.1/app/run.js
 -r -d=/Users/manos/workspace/sarissa/target/site//jsdoc 
/Users/manos/workspace/sarissa/src/main/js/gr/abiss/js/sarissa/sarissa.js
/Users/manos/workspace/sarissa/src/main/js/gr/abiss/js/sarissa/sarissa_ieemu_xpa
th.js



I'd say the -r option should be irrelevant when specific files are given to
JSDoc for processing.

add @since or @version to support version control

[deleted issue]

Version: 1.0.1

js: "../utilities/helper
scripts/jsdoc-rhino/jsdoc_toolkit-1.0.1/app/JsToke.js", line 383: uncaught
JavaScript runtime exception: TypeError: Cannot call method "is" of undefined

Current:
    if (stream.look() == "/"
     && !tokens.last().is("NUMB")
     && !tokens.last().is("NAME")
     && !tokens.last().is("RIGHT_PAREN")
     && !tokens.last().is("RIGHT_BRACKET")
    ) {

Fixed:
    if (stream.look() == "/"
     && tokens.last()
     && !tokens.last().is("NUMB")
     && !tokens.last().is("NAME")
     && !tokens.last().is("RIGHT_PAREN")
     && !tokens.last().is("RIGHT_BRACKET")
    ) {

I would attach the source file that generated the error, but I'm not at
liberty to do so.

The perl jsdoc supports @returns as a synonym for @return
http://jsdoc.sourceforge.net/

I did not see that @returns was supported by javadoc.
http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#javadocta
gs

The issue is whether it should be supported or not.

Would it be possible to have multiple return values? Is that desirable?

[deleted issue]

Reported by stuart.grimshaw...

I get the following error when trying to document another 3rd party lib

Tokenizing: file 40, C:\Files\Workspaces\ENTERPRISE\src\Sdl
\Enterprise\Web\website\themes\default\js\ceaf\/yui/button/button-beta-
debug.js
     8957 tokens found.
     10 symbols found.
js: "C:\Program Files\jsdoc_toolkit-1.1\app/JsDoc.js", line 119:
uncaught JavaScript runtime exception: TypeError: Cannot read property
"methods" from undefined

My solution has been to change line 119 to:

if(base)
{
   parser.symbols[s].inheritedMethods =
   parser.symbols[s].inheritedMethods.concat(base.methods);
}

Which seems to have worked.

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

1.3.0, on Linux


Please provide any additional information below.

The old JSDoc supports @link (turning into an A tag with an HREF, in HTML),
as well as @see tags.

Those two accept the same following syntax:
@link/see MyType#myFunOrStaticFunOrStaticVariable
@link/see MYNAMESPACE.MyType
@link/see MYNAMESPACE.MyType#myFunOrStaticFunOrStaticVariable

Note that the @link tag can be used inline, like in:
<js file>
[...]
/**
 * @constructor
 *
 * @extends MYNAMESPACE.MyParentType
 *
 * @class
 * This type does the same as that {@link MYNAMESPACE.MyParentType}, except
that it throws fireballs as a bonus.
 * 
 * @param [...]
 */
MYNAMESPACE.MyType = function () {
    [...]
};
[...]
</js file>

We have a huge JSDoc-compatible codebase which we definitely don't want to
re-document, especially since those tags have no equivalent so far in JSDoc
Toolkit, it seems.

Could those be supported in upcoming releases?

Also, JSDoc Toolkit doesn't seem to recognize the @extends tag. 
Can that be supported too in later releases?

Best,
        Arnaud

What steps will reproduce the problem?

function Person(){}
Person.prototype.setName = function(name) {
    this.name = name;
} 

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

name should be seen as a property of the Person instance {Person}.name but
instead appears as a property of the method, like {Person}.setName.name

What steps will reproduce the problem?

Run the JsDoc Toolkit without some required option, -t for example.

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

Since no output is possible without a template a warning or error should be
visible. Instead the process runs quietly with no indication of missing
options, and no output is produced.

What steps will reproduce the problem?
1. with the attached javascript issue the following command...
2. java -jar app/js.jar app/run.js -a t=templates/htm variables_properties.js 

What is the expected output? What do you see instead?
I would like to see documentation a constructor with property tags. 
Instead no property tags are generated

What version of the product are you using? On what operating system?
This is using jsdoc-toolkit_1.0.3 on a windows xp system

Please provide any additional information below.

The same result happens if the object status is commented with a
@constructor tag or not.

[deleted issue]

Add link to source code, with syntax hiliting.

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

A tree of inheritance, between types; something like

AbstractButton
|
+--ImageButton
   |
   +--DockImageButton

with each entry being a link to the doc of that particular type.
Instead, there's nothing, so far.

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

1.3.0, on Linux

Please provide any additional information below.

What steps will reproduce the problem?
1. put /** @method */ above prototype method
2. run JsDoc Toolkit 1.0.2
3. methods not include in documents generated

What is the expected output? What do you see instead?
method documentation. I see nothing, only function (@function), properties 
(@field) and classes (@class)

What version of the product are you using? On what operating system?
1.0.2 on Windows XP

Please provide any additional information below.

I did this in my .js file:
/** 
 * Method that will be called to start the application
 * @method
 */       
    start:  function(){ 
        // some coding
    },

but it's not documented...
In 0.5.2 it worked using these tags

Thanks

What steps will reproduce the problem?
1. use @config with square brackets (@config {foo} [bar] a bar of type foo)

What is the expected output? What do you see instead?
I was hoping to get an optional property but instead, the name is blank 
and [bar] is part of the description

What version of the product are you using? On what operating system?
JsDoc 1.3.2 on XP

Please provide any additional information below.
Consider having an API that gets an object as a parameter:

myFunction({hello:"world"})

That object is not a "solid" Object, but rather a subset from 
{hello:"some-string", goodbye:"some-string"} meaning that "goodbye" is an 
optional property of the first parameter of myFunction

The parser was not finding the methods withing objects declared in the
following way:

Foo = function(id)
{
   Foo.prototype.methodOne = function(bar) {
      alert(bar);
   };

   Foo.prototype.methodTwo = function(bar2) {
      alert(bar2);
   };
};

Simply modifying JsParse.js at line 295, inserting the following right
after the check for "this._findDocComment(fs)" fixed the issue:

      else if (this._findFunction(fs)) {

      }

What version of the product are you using? On what operating system?
jsdoctoolkit_1.3.0 / Windows XP

What steps will reproduce the problem?
Using the following syntax:
/**
 * My function documentation goes here ...
 */
myClass = function() {};
myClass.prototype = {
  /**
   * Here is a visible function
   */
  myFunc : function (){},
  /**
   * Here should be a 'hidden' function
   */
  _myHiddenFunc : function() {}
};

What is the expected output? What do you see instead?
Only myFunc should be documented in output not '_myHiddenFunc' unless I use
-A as a parameter.

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

1.02 Windows

Please provide any additional information below.

What steps will reproduce the problem?
1. Use the fileOverview tag

What is the expected output? What do you see instead?
The default description when there is no overview is "No overview 
provided". 
Expected: the default overview descripiton should be empty.

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

Please provide any additional information below.

V-1.1.1

In 1.0.1 I was able to use paths relative to the current working directory.
In 1.1.1 it's relative to the toolkit directory.

I wanted to mimic the behavior from 1.0.1

java -Djsdoc.dir=%JSDOC_BASE% -jar %RHINO% %JSDOC%  -A -d=%OUTPUT_DIR%
-t=%TEMPLATE% -x=%EXTENSIONS% relative_path\*

Changed in run.js
- __DIR__
- require()

var __DIR__ = System.getProperty("jsdoc.dir") ||
System.getProperty("user.dir");

function require(lib)
{
    var arrSearchDirs = ['',__DIR__,__DIR__+'/app/',__DIR__+'../'];
    var arrErrors = [];
    for(var idx=0;idx<arrSearchDirs.length;idx++)
    {
        var strDir = arrSearchDirs[idx];
        try
        {
            var file = new Packages.java.io.File(strDir+lib);
            if(!file.exists())
            {
                arrErrors.push('Could not find: ['+(strDir+lib)+']');
            }
            else
            {
                print("Loading: ["+(strDir+lib)+"] ...");
                load(strDir+lib);
                return;
            }
        }
        catch (e)
        {
            arrErrors.push('Error loading: ['+(strDir+lib)+']');
        }
    }
    for(var idx=0;idx<arrErrors.length;idx++)
    {
        print("ERROR: ["+arrErrors[idx]+"]");
    }
    quit();
}

The @inherits tag should be a synonym for the @extends tag.

What steps will reproduce the problem?
1. Run JsDocTK against a source code file encoded as UTF-8 with BOM (byte
order mark).
2. Click the "view source" link in the output.

What is the expected output? What do you see instead?
The syntax hilited view has two garbled characters showing at the start of
the file -- these are the hi-bit BOM characters that were improperly
translated.

What steps will reproduce the problem?
1. run JsDoc toolkit with the full path to a source file.


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

Should have a working view source link in the output but instead the view
source is empty.

What steps will reproduce the problem?

The same example from the Wiki pages:

/** * Change the role of the employee.
 * @param {integer} employeeId The id of the employee.
 * @param {string} [newRole] The new role of the employee.
 */

function recast(employeeId, newRole) {}

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

newRole parameter should be optional, instead there is no isOptional 
attribute in the xml

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

Please provide any additional information below.

What steps will reproduce the problem?

foo = new function(){
    this.bar = function(){}
}()


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

foo.bar should be a simple function, but instead it is interpreted as a
method of a non-existent constructor "foo."

[deleted issue]