Rails spinoffs - Jan 2008 - Prototype.js with jsDoc-toolkit?

Is anyone else using jsdoc-toolkit with Prototype.js? It works great
on plain ''ol JavaScript, but seems to have some problems using
Prototype 1.6-style classes and inheritance.

For example, if I do something like:

<code>
/**
 * @class Foo
 * @extends Bar
 */
 Foo = Class.create(Bar, {
   /**
    * @constructor
    */
  initialize : function() {
    /**
     * An important number
     * @type Number
     */
   this.important_number = 9999;
    // do more stuff
 },
 /**
  * This function does something else
  * @return {Object} Something
  */
 anotherFunction : function() {

  ...snip...

});
</code>

It has some problems:

1. I have to declare it as @class.
2. ''Bar'' is not recognized as the superclass.
3. I have to declare initialize as @constructor.
4. The comments for the object properties (this.important_number)
(done either before or in the initialize method) do not show up at all
in the generated documentation.
5. anotherFunction() will not show up in the docs as a method of class
Foo.

I fully realize that jsdoc-toolkit was not designed with this use in
mind, and when this code is being parsed it appears to jsdoc that this
whole declaration was nothing more than a variable being assigned to
the result of a function.

I''m not complaining about jsdoc''s inablility to handle this,
just
wondering if anyone else was using jsdoc in this manner and had any
thoughts or advice on changing my coding style or the best way to go
about customizing jsdoc for this use.

If I can come up with a patch for jsdoc I would gladly share it if
anyone else is interested.

Thanks,

Nathan
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Spinoffs" group.
To post to this group, send email to
rubyonrails-spinoffs-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-spinoffs-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-spinoffs?hl=en
-~----------~----~----~----~------~----~------~--~---

Michael,

Thanks so much for your quick reply. Most of your suggestions worked,
but I''ll detail a couple of problems I''m still having.
> > 3. I have to declare initialize as @constructor.
>
> I wouldn''t. That would only confuse JsDoc. Again, I don''t
know what
> Prototype does behind it''s back, but if initialize() is a method
of
> Foo, then you definitely shouldn''t decalare it a @constructor. In
this
> case I woul''s, and in fact in JavaScript''s, understanding
of things
> there is no difference (JavaScript really has no class).
jsdoc appears to work the same way in this situation whether or not I
use the @construtor directive, so just leaving it out works. I''m
coming from Ruby, where ''initialize'' actually *is* the
constructor
(even though you use ''new'' to instantiate a class), and
Prototype
tries to mimic this idiom. A good description of the way classes and
inheritance works in Prototype 1.6 is here:
http://www.prototypejs.org/learn/class-inheritance.
Apparently the constructor calls the initialize method when a
''class''
is created.
> > 4. The comments for the object properties (this.important_number)
> > (done either before or in the initialize method) do not show up at all
>
> They do, in the example I give later, but there is a significant issue
> to watch out for in JsDoc Toolkit 1.x in this regard: it doesn''t
> recognize the "this" in initialize() as meaning Foo (the nearest
> containing constructor) and instead treats important_number like a
> property of initialize(). I''d call that a bug. Again, you can work
> around this with the @name tag, but, you may be pleased to know, this
> issue is fixed in JsDoc toolkit 2.0 (which is now in alpha). So the
> workaround won''t be required for much longer.
I tried adding a @name directive to my properties, but they still
don''t seem to show up. I''ve had the -a option on. Will an svn
checkout
get me the 2.0 alpha?


Everything else you suggested worked perfectly.

I''m wondering what I could do to streamline this to work with my code
a little better. I haven''t dug into the jsdoc source much, but it
would be really cool to customize the code to automatically place a ''/
** @scope Foo.prototype */'' before any object literal argument in a
Foo = Class.create({...}) statement, or automatically set @extends
when parent or mixin classes are passed to Class.create as arguments.

This kind of thing doesn''t sound like it should be included in the
jsdoc-toolkit core, but there are a few projects (Prototype,
inheritance.js [http://www.twologic.com/projects/inheritance/], and
surely others) that that mess with the way JavaScript handles classes
and such, and it would be great to have some kind of mechanism to have
jsdoc work well with them.

Thanks again for all your help; it''s a great project. I think
we''ve
gotten this far enough along where I can use it on my projects, and
any other suggestions would be appreciated.

Nathan
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Spinoffs" group.
To post to this group, send email to
rubyonrails-spinoffs-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-spinoffs-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-spinoffs?hl=en
-~----------~----~----~----~------~----~------~--~---