jsdoc-user

[Jsdoc-user] Documenting and oject

[Peter M. <pet...@gm...>]

Hi,

I have been happily using JSDoc to document my JavaScript "classes".
Can I document a JavaScript object created with an object literal?
Something like

/**
 * @object
 *
 * This is my foo object.
 */
var foo = {
  /**
   * The bar function property.
   */
  bar: function(){},
  /**
   * The barbar array property.
   */
  barbar: []
};

Thanks,
Peter

Re: [Jsdoc-user] Documenting and oject

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

Hi,

> I have been happily using JSDoc to document my JavaScript "classes".
> Can I document a JavaScript object created with an object literal?
> Something like
> 
> /**
>  * @object
>  *
>  * This is my foo object.
>  */
> var foo = {
>   /**
>    * The bar function property.
>    */
>   bar: function(){},
>   /**
>    * The barbar array property.
>    */
>   barbar: []
> };
> 

Unfortunately, no, the current version of JSDoc doesn't document global
objects like this, although it does seem to be something that is asked
for quite often.

As was pointed out by Ian Peterson earlier today on this list, your
code can be slightly changed (without changing the functionality of it)
to allow it to be documented by JSDoc, as shown below:

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

I'm not too crazy about the idea of users having to change their code to
adapt to the tool, but as I said, that's the current situation.

Regards,

    Gabriel

Re: [Jsdoc-user] Documenting and oject

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

> >your
> >code can be slightly changed (without changing the functionality of it)
> >to allow it to be documented by JSDoc, as shown below:
> >
> >var foo;
> >foo = new function(){
> >    this.bar = function(){};
> >};
> >
> >I'm not too crazy about the idea of users having to change their code to
> >adapt to the tool, but as I said, that's the current situation.
> 
> No, I  don't want to change my code to enable the JSDoc tool to pick
> up the docs. I've seen that the Yahoo! UI uses a trick similar to
> this.
> 
> Is there a move to add this functionality to JSDoc? It seems essential
> to documenting JavaScript code.

I suppose you could say that there is very slight motion in the
direction of supporting this, but it won't be happening today or
tomorrow.

The original intention of JSDoc was to document prototype/class/object
-oriented JavaScript. It has been adapted more and more along the way to
try to handle broader needs such as the one you're describing, but now
it has gotten quite difficult to handle adding functionality like this. 

The "slight motion" that I refer to is the (partial) re-implementation
of JSDoc using a real JavaScript parser/interpreter, instead of fumbling
around with regexes as is done now. I would say that this is in the
general planning phase right now (and has been for a while now), which
is why the functionality that you're talking about won't be ready in the
very near future.

Regards,

    Gabriel