finally fed up with jsdoc

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

finally fed up with jsdoc

Christopher Schmidt-2
I finally got fed up with JSDoc today. It's now segfaulting even with
the lower recursion depth on the regexes, which means that the only way
to get anything out of it is to set it up so we get practically nothing
out of it.

So, I sat down and wrote out something that replaces a significant chunk
of the jsdoc functionality we were using. The code right now is
super-crappy, but it seems like our code is well structured enough that
this isn't going to be a horribly hard task.

You can see the current output at:

http://crschmidt.net/~crschmidt/out/

Some examples:

 http://crschmidt.net/~crschmidt/out/OpenLayers/Map.html#theme
 http://crschmidt.net/~crschmidt/out/OpenLayers/Layer.html#getViewPortPxFromLonLat

etc.

Note that changing to this solution is no longer an option of 'if', but
'when'. Despite lots of time and effort put into babying jsdoc, we have
simply grown past a point where it is viable, and huge chunks of our
documentation simply aren't covered by the jsdoc parser.

If someone wants to hack on jsdoc to try to fix these issues, they can feel
free, but I'm not hopeful that we'll get a resolution of this that way,
which is why I'm pursuing the new solution, which I at least understand
the *reasons* it breaks, when it does.

Regards,
--
Christopher Schmidt
MetaCarta
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: finally fed up with jsdoc

Cameron Shorter
Nice,
I assume you plan to feed your hacks back into the jsdoc codebase?

I'm hoping we can use the same tool to jsdoc mapbuilder, which includes
openlayers code.

Christopher Schmidt wrote:

> I finally got fed up with JSDoc today. It's now segfaulting even with
> the lower recursion depth on the regexes, which means that the only way
> to get anything out of it is to set it up so we get practically nothing
> out of it.
>
> So, I sat down and wrote out something that replaces a significant chunk
> of the jsdoc functionality we were using. The code right now is
> super-crappy, but it seems like our code is well structured enough that
> this isn't going to be a horribly hard task.
>
> You can see the current output at:
>
> http://crschmidt.net/~crschmidt/out/
>
> Some examples:
>
>  http://crschmidt.net/~crschmidt/out/OpenLayers/Map.html#theme
>  http://crschmidt.net/~crschmidt/out/OpenLayers/Layer.html#getViewPortPxFromLonLat
>
> etc.
>
> Note that changing to this solution is no longer an option of 'if', but
> 'when'. Despite lots of time and effort put into babying jsdoc, we have
> simply grown past a point where it is viable, and huge chunks of our
> documentation simply aren't covered by the jsdoc parser.
>
> If someone wants to hack on jsdoc to try to fix these issues, they can feel
> free, but I'm not hopeful that we'll get a resolution of this that way,
> which is why I'm pursuing the new solution, which I at least understand
> the *reasons* it breaks, when it does.
>
> Regards,
>  


--
Cameron Shorter
Systems Architect, http://lisasoft.com.au
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: finally fed up with jsdoc

Christopher Schmidt-2
On Mon, Jun 18, 2007 at 09:45:45AM +1000, Cameron Shorter wrote:
> Nice,
> I assume you plan to feed your hacks back into the jsdoc codebase?

Not particularly. The code will be published with OpenLayers -- so
anyone would be able to do that, if they cared -- but it's not an
improvement of JSDoc, it's a complete rewrite in a different language,
specifically targeted towards the style of code and commenting we use in
OpenLayers, not a general Javascript docuemntation tool.  

> I'm hoping we can use the same tool to jsdoc mapbuilder, which includes
> openlayers code.

I wouldn't be too hopeful. It's very specific to our code, and I don't
plan to create and maintain a tool like that (though others are, again,
welcome to).

Regards,
--
Christopher Schmidt
MetaCarta
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: finally fed up with jsdoc

Paul Spencer-2
In reply to this post by Christopher Schmidt-2
Chris,

I think this is a great idea.  I assume you've done it in python :)  
Can you give a brief description of what it is about the OL code that  
it uses - i.e. is it just the particular prototype-style of  
declaration or is it something specific in the comments that is  
formatted in a particular way that it relies on.  I think that we  
should document and enforce a comment style guide to ensure that this  
requires minimal maintenance in the future.

Cheers

Paul

On 17-Jun-07, at 12:03 AM, Christopher Schmidt wrote:

> I finally got fed up with JSDoc today. It's now segfaulting even with
> the lower recursion depth on the regexes, which means that the only  
> way
> to get anything out of it is to set it up so we get practically  
> nothing
> out of it.
>
> So, I sat down and wrote out something that replaces a significant  
> chunk
> of the jsdoc functionality we were using. The code right now is
> super-crappy, but it seems like our code is well structured enough  
> that
> this isn't going to be a horribly hard task.
>
> You can see the current output at:
>
> http://crschmidt.net/~crschmidt/out/
>
> Some examples:
>
>  http://crschmidt.net/~crschmidt/out/OpenLayers/Map.html#theme
>  http://crschmidt.net/~crschmidt/out/OpenLayers/ 
> Layer.html#getViewPortPxFromLonLat
>
> etc.
>
> Note that changing to this solution is no longer an option of 'if',  
> but
> 'when'. Despite lots of time and effort put into babying jsdoc, we  
> have
> simply grown past a point where it is viable, and huge chunks of our
> documentation simply aren't covered by the jsdoc parser.
>
> If someone wants to hack on jsdoc to try to fix these issues, they  
> can feel
> free, but I'm not hopeful that we'll get a resolution of this that  
> way,
> which is why I'm pursuing the new solution, which I at least  
> understand
> the *reasons* it breaks, when it does.
>
> Regards,
> --
> Christopher Schmidt
> MetaCarta
> _______________________________________________
> Dev mailing list
> [hidden email]
> http://openlayers.org/mailman/listinfo/dev

+-----------------------------------------------------------------+
|Paul Spencer                          [hidden email]    |
+-----------------------------------------------------------------+
|Chief Technology Officer                                         |
|DM Solutions Group Inc                http://www.dmsolutions.ca/ |
+-----------------------------------------------------------------+





_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: finally fed up with jsdoc

Glen Stampoultzis-2
In reply to this post by Christopher Schmidt-2
How about Natural Docs?

http://naturaldocs.org/

MooTools seems to use it and their documentation looks great.

It would require rewriting the existing tags but I'd be happy to volunteer for that if you'd like.

Regards,

Glen Stampoultzis

On 17/06/07, Christopher Schmidt <[hidden email]> wrote:
I finally got fed up with JSDoc today. It's now segfaulting even with
the lower recursion depth on the regexes, which means that the only way
to get anything out of it is to set it up so we get practically nothing
out of it.

So, I sat down and wrote out something that replaces a significant chunk
of the jsdoc functionality we were using. The code right now is
super-crappy, but it seems like our code is well structured enough that
this isn't going to be a horribly hard task.

You can see the current output at:

http://crschmidt.net/~crschmidt/out/

Some examples:

http://crschmidt.net/~crschmidt/out/OpenLayers/Map.html#theme
http://crschmidt.net/~crschmidt/out/OpenLayers/Layer.html#getViewPortPxFromLonLat

etc.

Note that changing to this solution is no longer an option of 'if', but
'when'. Despite lots of time and effort put into babying jsdoc, we have
simply grown past a point where it is viable, and huge chunks of our
documentation simply aren't covered by the jsdoc parser.

If someone wants to hack on jsdoc to try to fix these issues, they can feel
free, but I'm not hopeful that we'll get a resolution of this that way,
which is why I'm pursuing the new solution, which I at least understand
the *reasons* it breaks, when it does.

Regards,
--
Christopher Schmidt
MetaCarta
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev


_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: finally fed up with jsdoc

Tim Schaub-2
Hey-

Glen Stampoultzis wrote:
> How about Natural Docs?
>
> http://naturaldocs.org/
>

I'm all in favor of Natural Docs.  I just switched a small project over
to Natural Docs, and I like it.

Benefits-
Natural Docs comment style is designed to be very readable in the code
(see example below).  Output HTML docs generated from these comments are
pretty.  Comment style is flexible, and Natural Docs is easy to customize.

Drawbacks-
Function parameters aren't specified with type.  We can work around this
by agreeing on a convention for this.  Below is an example of comments
that do the right thing in Natural Docs (I've used brackets for
parameter type).  We may need to customize it to get class hierarchy in
the menu.  The JSForms project uses Natural Docs and has done this.

Natural Docs doesn't have full language support for JavaScript.  I
actually see this as an advantage.  I think we'll have more luck with
comment only documentation.

Quick example of something that produces very usable output in Natural
Docs.  Note that there is all kinds of support for generic topic
documentation - so pages can have a nice intro etc.

/**
  * Namespace: OpenLayers
  * The place for all things OpenLayers to live.
  */
OpenLayers = {
      /**
       * Property: [String] someProp
       * Description of someProp
       */
       someProp: "default",

      /**
       * Method: doSomething
       * Description of this method goes here
       *
       * Parameters:
       * map [<OpenLayers.Map>] - This map will have something done to it
       * options [Object] - An optional object with some properties
       *
       * Returns:
       * [Object] or maybe [<OpenLayers.Map>] Description of the return
       */
       doSomething: function(map, options) {
           // code here
       }
}

/**
  * Class: OpenLayers.Map
  * Instances of this class are nice maps.
  */
OpenLayers.Map = OpenLayers.Class.create();
OpenLayers.Map.prototype = {
     /**
      * Constructor: OpenLayers.Map
      * Create a new map.
      *
      * Example:
      * > var map = new OpenLayers.Map("mapid")
      *
      * Parameters:
      * id [String] - The id of the element that will contain the map
      * options [Object] - An optional object with some properties
      */
     initialize: function(id, options) {
         // code here
     },

     /**
      * Constant: CLASS_NAME
      */
     CLASS_NAME: "OpenLayers.Map"
}



_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Natural Docs

Tim Schaub-2
Hey again-

> Glen Stampoultzis wrote:
>> How about Natural Docs?
>>
>> http://naturaldocs.org/
>>

You can see OpenLayers API documentation starting to come together here:
http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc

Tim

_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Christopher Schmidt-2
On Wed, Jun 20, 2007 at 03:44:09PM -0600, Tim Schaub wrote:

> Hey again-
>
> > Glen Stampoultzis wrote:
> >> How about Natural Docs?
> >>
> >> http://naturaldocs.org/
> >>
>
> You can see OpenLayers API documentation starting to come together here:
> http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc

I hearby migrate any idea I might have had of maintaining my own stuff
to be fully in support of naturaldocs.

down with jsdoc, up with naturaldocs!

Regards,
--
Christopher Schmidt
MetaCarta
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Erik Uzureau-3
...and the yeahs have it!

<gulp/>

Tim can you make a ticket for this? I havent had the time to really
review it but it sounds like everyone is in favor, and just a brief
look at what you've done so far is *very* convincing :-)

Erik



On 6/20/07, Christopher Schmidt <[hidden email]> wrote:

> On Wed, Jun 20, 2007 at 03:44:09PM -0600, Tim Schaub wrote:
> > Hey again-
> >
> > > Glen Stampoultzis wrote:
> > >> How about Natural Docs?
> > >>
> > >> http://naturaldocs.org/
> > >>
> >
> > You can see OpenLayers API documentation starting to come together here:
> > http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc
>
> I hearby migrate any idea I might have had of maintaining my own stuff
> to be fully in support of naturaldocs.
>
> down with jsdoc, up with naturaldocs!
>
> Regards,
> --
> Christopher Schmidt
> MetaCarta
> _______________________________________________
> Dev mailing list
> [hidden email]
> http://openlayers.org/mailman/listinfo/dev
>
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Tim Schaub-2
Hey-

Erik Uzureau wrote:
> Tim can you make a ticket for this? I havent had the time to really
> review it but it sounds like everyone is in favor, and just a brief
> look at what you've done so far is *very* convincing :-)

See ticket #773 [1].

If anybody with commit access wants to work on changing the comment
style to work with Natural Docs, see the page I've put up for
OpenLayers/Natural Docs conventions [2].  Of course, reading the Natural
Docs documentation itself is also helpful [3].

This is only very partial documentation right now [4], but I think we
can make it real nice.

Tim

[1] http://trac.openlayers.org/ticket/773

[2] http://trac.openlayers.org/wiki/NaturalDocs

[3] http://www.naturaldocs.org/

[4] http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc

_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Paul Spencer-2
Nice work Tim.  I'm gonna start using Natural Docs for my stuff too!  
And I'll try to help out in OL ... time always being the issue.

Cheers

Paul

On 20-Jun-07, at 7:48 PM, Tim Schaub wrote:

> Hey-
>
> Erik Uzureau wrote:
>> Tim can you make a ticket for this? I havent had the time to really
>> review it but it sounds like everyone is in favor, and just a brief
>> look at what you've done so far is *very* convincing :-)
>
> See ticket #773 [1].
>
> If anybody with commit access wants to work on changing the comment
> style to work with Natural Docs, see the page I've put up for
> OpenLayers/Natural Docs conventions [2].  Of course, reading the  
> Natural
> Docs documentation itself is also helpful [3].
>
> This is only very partial documentation right now [4], but I think we
> can make it real nice.
>
> Tim
>
> [1] http://trac.openlayers.org/ticket/773
>
> [2] http://trac.openlayers.org/wiki/NaturalDocs
>
> [3] http://www.naturaldocs.org/
>
> [4] http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc
>
> _______________________________________________
> Dev mailing list
> [hidden email]
> http://openlayers.org/mailman/listinfo/dev

+-----------------------------------------------------------------+
|Paul Spencer                          [hidden email]    |
+-----------------------------------------------------------------+
|Chief Technology Officer                                         |
|DM Solutions Group Inc                http://www.dmsolutions.ca/ |
+-----------------------------------------------------------------+





_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Christopher Schmidt-2
In reply to this post by Tim Schaub-2
On Wed, Jun 20, 2007 at 05:48:47PM -0600, Tim Schaub wrote:

> Hey-
>
> Erik Uzureau wrote:
> > Tim can you make a ticket for this? I havent had the time to really
> > review it but it sounds like everyone is in favor, and just a brief
> > look at what you've done so far is *very* convincing :-)
>
> See ticket #773 [1].
>
> If anybody with commit access wants to work on changing the comment
> style to work with Natural Docs, see the page I've put up for
> OpenLayers/Natural Docs conventions [2].  Of course, reading the Natural
> Docs documentation itself is also helpful [3].
>
> This is only very partial documentation right now [4], but I think we
> can make it real nice.

I've been working on this for 3 hours or so, and have finished up
documentation for all of the Handlers, as well as the Events.js
file and a couple of layers.

I've also set up autogeneration of the documentation every 10 minutes,
going to http://dev.openlayers.org/naturaldocs/ .

I've also crafted a convention for private properties/methods: The first
word of the description should be "*Private*." The '.' means that the
description of the method won't appear in the overview, but it will
still appear in the longer description, and the *s make it bold. I think
this is clear enough from my observations. I've added this to the
NaturalDocs wikipage.

I'm probably going to stop on this for the next 12 hours or so, and
might get back to it tonight.

Regards,
--
Christopher Schmidt
MetaCarta
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Cameron Shorter
I'm catching up on email. I must say that I'm impressed with NaturalDocs
and agree that it is a good idea for Openlayers.

Christopher Schmidt wrote:

> On Wed, Jun 20, 2007 at 05:48:47PM -0600, Tim Schaub wrote:
>  
>> Hey-
>>
>> Erik Uzureau wrote:
>>    
>>> Tim can you make a ticket for this? I havent had the time to really
>>> review it but it sounds like everyone is in favor, and just a brief
>>> look at what you've done so far is *very* convincing :-)
>>>      
>> See ticket #773 [1].
>>
>> If anybody with commit access wants to work on changing the comment
>> style to work with Natural Docs, see the page I've put up for
>> OpenLayers/Natural Docs conventions [2].  Of course, reading the Natural
>> Docs documentation itself is also helpful [3].
>>
>> This is only very partial documentation right now [4], but I think we
>> can make it real nice.
>>    
>
> I've been working on this for 3 hours or so, and have finished up
> documentation for all of the Handlers, as well as the Events.js
> file and a couple of layers.
>
> I've also set up autogeneration of the documentation every 10 minutes,
> going to http://dev.openlayers.org/naturaldocs/ .
>
> I've also crafted a convention for private properties/methods: The first
> word of the description should be "*Private*." The '.' means that the
> description of the method won't appear in the overview, but it will
> still appear in the longer description, and the *s make it bold. I think
> this is clear enough from my observations. I've added this to the
> NaturalDocs wikipage.
>
> I'm probably going to stop on this for the next 12 hours or so, and
> might get back to it tonight.
>
> Regards,
>  


--
Cameron Shorter
Systems Architect, http://lisasoft.com.au
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Cameron Shorter
In reply to this post by Tim Schaub-2
I'm not sure if anyone has tried this:
http://www.naturaldocs.org/documentation/development/files/Modules/NaturalDocs/Parser/JavaDoc-pm.html

It converts Javadocs to NaturalDocs, so there is a pretty good chance it
would convert JSDocs to NaturalDocs too.

Cameron Shorter wrote:

> This is interesting. The Openlayers guys are switching over to
> NaturalDocs because JSDoc doesn't work for them.
>
> It offers a simple wiki like formatting which is pretty cool.
>
> I don't see an immediate need for it yet for mapbuilder as it would
> require changing all our code comments, but is something we might want
> to consider in the future, especially if the Openlayers classes we
> import break our JSDocs.
>
> Tim Schaub wrote:
>> Hey again-
>>
>>  
>>> Glen Stampoultzis wrote:
>>>    
>>>> How about Natural Docs?
>>>>
>>>> http://naturaldocs.org/
>>>>
>>>>      
>>
>> You can see OpenLayers API documentation starting to come together here:
>> http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc
>>
>> Tim
>>
>> _______________________________________________
>> Dev mailing list
>> [hidden email]
>> http://openlayers.org/mailman/listinfo/dev
>>
>>  
>
>


--
Cameron Shorter
Systems Architect, http://lisasoft.com.au
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev
Reply | Threaded
Open this post in threaded view
|

Re: Natural Docs

Erik Uzureau-3
Hmm. This looks good. I think Tim might be MIA for a couple of days
but when he gets back maybe we can see if he tried this.

--E

On 6/22/07, Cameron Shorter <[hidden email]> wrote:

> I'm not sure if anyone has tried this:
> http://www.naturaldocs.org/documentation/development/files/Modules/NaturalDocs/Parser/JavaDoc-pm.html
>
> It converts Javadocs to NaturalDocs, so there is a pretty good chance it
> would convert JSDocs to NaturalDocs too.
>
> Cameron Shorter wrote:
> > This is interesting. The Openlayers guys are switching over to
> > NaturalDocs because JSDoc doesn't work for them.
> >
> > It offers a simple wiki like formatting which is pretty cool.
> >
> > I don't see an immediate need for it yet for mapbuilder as it would
> > require changing all our code comments, but is something we might want
> > to consider in the future, especially if the Openlayers classes we
> > import break our JSDocs.
> >
> > Tim Schaub wrote:
> >> Hey again-
> >>
> >>
> >>> Glen Stampoultzis wrote:
> >>>
> >>>> How about Natural Docs?
> >>>>
> >>>> http://naturaldocs.org/
> >>>>
> >>>>
> >>
> >> You can see OpenLayers API documentation starting to come together here:
> >> http://dev.openlayers.org/sandbox/tschaub/naturaldocs/doc
> >>
> >> Tim
> >>
> >> _______________________________________________
> >> Dev mailing list
> >> [hidden email]
> >> http://openlayers.org/mailman/listinfo/dev
> >>
> >>
> >
> >
>
>
> --
> Cameron Shorter
> Systems Architect, http://lisasoft.com.au
> Tel: +61 (0)2 8570 5050
> Mob: +61 (0)419 142 254
>
> _______________________________________________
> Dev mailing list
> [hidden email]
> http://openlayers.org/mailman/listinfo/dev
>
_______________________________________________
Dev mailing list
[hidden email]
http://openlayers.org/mailman/listinfo/dev