jsdoc-user

[Jsdoc-user] generated HTML missing method details unless class used

[<bru...@wa...>]

here is a copy of a posting to the bug list...[Im not sure how often that 
is monitored
since all the other bugs in the list haven't been assigned and some are 
over a
year old]...


When the attached file is processed with 1.9.8 it
produces HTML missing the documention for each of the
methods of the single class in this file (Map).

However, if the very last line [which simply does a
"new Map()" ] is uncommented, then the proper HTML is
produced.

The code should not have to actually use a class in
order for that class to be documented!

I have verified that there can be arbitrary amounts of
code added to the file, and as long as Map is
instantiated somewhere in that code, Map methods are
properly documented in the HTML but not otherwise.

Re: [Jsdoc-user] generated HTML missing method details unless class used

[Gabriel R. <gab...@gm...>]

On Fri, Jan 06, 2006 at 11:32:25AM -0500, bru...@wa... wrote:
> here is a copy of a posting to the bug list...[Im not sure how often that 
> is monitored
> since all the other bugs in the list haven't been assigned and some are 
> over a
> year old]...

Actually, the bugs list is indeed monitored quite regularly. The bugs
that are still up there are generally (currently) not really solvable.
They don't get assigned because there's only me to assign them to myself :)

> When the attached file is processed with 1.9.8 it
> produces HTML missing the documention for each of the
> methods of the single class in this file (Map).
> 
> However, if the very last line [which simply does a
> "new Map()" ] is uncommented, then the proper HTML is
> produced.
> 
> The code should not have to actually use a class in
> order for that class to be documented!
> 
> I have verified that there can be arbitrary amounts of
> code added to the file, and as long as Map is
> instantiated somewhere in that code, Map methods are
> properly documented in the HTML but not otherwise.

JSDoc doesn't recognize Map as being a constructor without the call to
it. This can also be accomplished by adding a @constructor tag to Map's
documentation block. The next release of JSDoc won't require a
@constructor tag if the @class tag is used for the same function (which
is the case in your file). 

Gabriel

Re: [Jsdoc-user] generated HTML missing method details unless class used

[Gabriel R. <gab...@gm...>]

On Fri, Jan 06, 2006 at 01:33:02PM -0500, bru...@wa... wrote:
> thanks.
> BTW(1), when trying to test your suggestion, I tried the little file 
> attached
> and JsDoc failed and said...
> Loading sources from observer3.js
> Can't use an undefined value as an ARRAY reference at 
> c:\JSDoc-1.9.8\jsdoc.pl line 1096.

This has been fixed in JSDoc 1.9.8.1. Thanks for pointing it out.

> BTW(2), here is an enhancement request....
> Allow filenames in the @requires tag (at least in the comment block with 
> @fileoverview)
> so that one .js file can note its dependence on other .js files.
> While JsDoc will place the referenced file in the HTML in plain text,
> it gives error messages when running JsDoc. Also, it would be nice for
> the filename to actually be a link in the HTML to the referenced .js file
> thanks, Bruce Wallace

Could you register this as an RFE on sourceforge.net? By the way, you
can alter the handling of '@' tags in the .jsdoc_config file. When this
does get implemented, it will probably be introduced as an entry in that
file, as this is quite a customized request. If you'd like a hand with
adding this to your .jsdoc_config file, just let me know.

Gabriel