Re: Motivation to move from JsDoc Toolkit v2 to JsDoc v3 and Interoperability with Languages.

[Michael]

--

Michael

On 6 Jan 2013, at 06:49, gau...@rcorp.co.in wrote:

First off let me just say jsDoc Rocks! Its way better than sphinx, doxygen etc

Aww thanks! It's not really a competition or anything, but it's nice to know we've made someone happy.

At our organisation (www.rcorp.co.in) we started off with off-hand js with jQuery and used jsDoc Toolkit v2 (http://code.google.com/p/jsdoc-toolkit/). Our applications grew bigger and bigger and we started to design our own template for jsDoc. Infact, we were even considering making a Web 2.0 product related to online documentation using jsDoc.

Now we've switched to Dojo from jQuery as the sizes of our client side web apps has grown massive. Also, we have an independent division working on php (WordPress). With jsDoc Toolkit v2 we used custom tags to document phpdoc style tags for our PHP projects, with the -x attribute...

jsDoc3 is now being developed but I don't see an option whereby we can use it to document PHP code as well. WordPress Core is littered with phpdoc tags
but... phpdoc, well, sucks!

The option to ignore the code and only generate docs from JSDoc comments does not (yet) exist in JSDoc 3, but it would be an interesting and fairly straightforward job to add that. We've tried using a single documentation format for JS and PHP at my job and found no single tool or comment syntax that is perfect at both (including JSDoc). But I definitely understand the desire for consolidation in this domain. 

The dojo toolkit has its own api (beautiful) that is also generated via a different form of jsdoc viz this. To make our code compatible to the Dojo Toolkit we have to generate an XML like so. Notice <parameter> <description> <argument> <return-type>.

At an organisational level, irrespective of language we want to have a unified documentation standard as far as possible. Because we use Dojo and WordPress, Bootstrap and other frameworks, we can't rewrite the documentation of the core files of any framework. jsDoc v2 enabled us to create custom tags and custom output to overcome all these challenges. 

The opportunity of interoperability with v2 was beautiful...

To sum up here are some of the questions I'd like to ask.

1. What is the status of jsDoc Toolkit v2? Will it be actively developed?
   

It's unlikely that the v2 branch will get as much attention as v3, unless someone wants to basically fork JSDoc and start adding new features and fixes to v2. Version 3 is the focus now and it will probably get a greater bump in interest when it finally gains support for a NodeJS engine. I haven't heard any murmurs from anyone volunteering to take on the maintainer role for v3.

2. Will jsDoc3 be backwards compatible with jsDoc toolkit v2? In terms of creating templates for either as well as documented source code that works in v2?
   

No. The uptick in the major version number means we're breaking backwards comparability. The templates will definitely not be cross-compatible, but actually the doc comments are probably 90% compatible, with the difference being mostly additions and shortcuts added to v3. It isn't 100% though so there will likely be at least a small amount of work to upgrade. 

3. If not, will it at least support the same functionalities present in v2? Most specifically using it to document non JS code?

Version 3 does not support non-JS, or even invalid JS for that matter, but as I said it would be fairly straight forward to add an option to ignore the code entirely, and if you did that you could then document any code, even non-JS. I might volunteer to look into that sometime but I can't promise a delivery date or anything. 

3. If not, we can create a plugin so the entire PHPDoc community (PHP.net, WordPress, Joomla, Drupal etc.) and maybe later other languages can start using jsDoc?
   

It would be more than a plugin, you would need to write a whole new parser, but such a parser would only need to be able to find doc comments amongst the gobbledygook, and even a decent regex should be sufficient for that.

4. Is jsDoc able to produce an XML file like this? If not, any guidelines on how to go about building a plugin or something for it? If we are able to do this, the entire Dojo Community can start using jsDoc.

Version 3 has a template that will produce JSON, and I think it either does or can be adapted to produce XML fairly easily. It's the Haruki template as I recall.

5. What does jsDoc v2 lack generally? I know jsDoc3 adds lots of new tags, but are there any major structural changes in the way both of them work?

Generally version 3 doesn't use the homemade simple parser I wrote, and instead uses the awesome power of Mozilla's parser. That solves some significant problems that JSDoc v2 simply can never deal with, like documenting a var with multiple variable declarations. That was the biggest motivation to create v3, but I also took the opportunity to add support for JS modules and to clean up the supported tag set a little. Interestingly, the upcoming work on v3 will actually involve removing the dependency on Mozilla's parser, so a suitable node-comparable replacement will have to be found.

I'm sorry to bother the jsdoc community with such a long post. In my defence, once some of these questions are settled, our organisation plans to help out the community in terms of Templates, Plugins, Pull Requests and Issues. We were anyway making patches to jsDoc v2 before we found out its being superseded by jsDoc3.

If you have a fondness for v2 and want to adopt it, you certainly can take on maintainership of it, but I think you'd get more mileage out of contributing to v3. Jeff is driving v3 now and is quite open to pull requests.

Thanks!

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/dL3NpAdrutsJ.
To post to this group, send email to jsdoc...@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.

[Jeff Williams]

Thanks for the kind words! (And Michael, thanks for your detailed reply!)

I've just created a JSDoc 3 "commentsOnly" plugin that forces JSDoc to ignore everything in source files except JSDoc comments. By enabling this plugin, you can use JSDoc to process PHP files, or any other source files that are not valid JavaScript. To use the plugin:

1. Get the very latest version of JSDoc 3 from GitHub.
2. If you don't already have a conf.json file in your JSDoc directory, copy conf.json.EXAMPLE to conf.json.
3. In conf.json, change the value of the "plugins" property from [] to ["plugins/commentsOnly"].

The plugin has only been tested a little, so if you find any bugs, please let me know.

Also, as Michael said, you can use the Haruki template to generate XML output. Try running the following command:

./jsdoc -t templates/haruki -d console -q format=xml [sourceFiles]

Haruki's XML output includes less information than JSDoc's usual output, but you could easily create a customized version of Haruki to meet your own needs.

I hope this helps, and I look forward to your contributions to JSDoc 3!

- Jeff

On Sat, Jan 5, 2013 at 10:49 PM, <gau...@rcorp.co.in> wrote:

First off let me just say jsDoc Rocks! Its way better than sphinx, doxygen etc etc.

At our organisation (www.rcorp.co.in) we started off with off-hand js with jQuery and used jsDoc Toolkit v2 (http://code.google.com/p/jsdoc-toolkit/). Our applications grew bigger and bigger and we started to design our own template for jsDoc. Infact, we were even considering making a Web 2.0 product related to online documentation using jsDoc.

Now we've switched to Dojo from jQuery as the sizes of our client side web apps has grown massive. Also, we have an independent division working on php (WordPress). With jsDoc Toolkit v2 we used custom tags to document phpdoc style tags for our PHP projects, with the -x attribute...

jsDoc3 is now being developed but I don't see an option whereby we can use it to document PHP code as well. WordPress Core is littered with phpdoc tags
but... phpdoc, well, sucks!

The dojo toolkit has its own api (beautiful) that is also generated via a different form of jsdoc viz this. To make our code compatible to the Dojo Toolkit we have to generate an XML like so. Notice <parameter> <description> <argument> <return-type>.

At an organisational level, irrespective of language we want to have a unified documentation standard as far as possible. Because we use Dojo and WordPress, Bootstrap and other frameworks, we can't rewrite the documentation of the core files of any framework. jsDoc v2 enabled us to create custom tags and custom output to overcome all these challenges. 

The opportunity of interoperability with v2 was beautiful...

To sum up here are some of the questions I'd like to ask.

1. What is the status of jsDoc Toolkit v2? Will it be actively developed?
   

1. Will jsDoc3 be backwards compatible with jsDoc toolkit v2? In terms of creating templates for either as well as documented source code that works in v2?
   

1. If not, will it at least support the same functionalities present in v2? Most specifically using it to document non JS code? If not, we can create a plugin so the entire PHPDoc community (PHP.net, WordPress, Joomla, Drupal etc.) and maybe later other languages can start using jsDoc?
   

1. Is jsDoc able to produce an XML file like this? If not, any guidelines on how to go about building a plugin or something for it? If we are able to do this, the entire Dojo Community can start using jsDoc.

1. What does jsDoc v2 lack generally? I know jsDoc3 adds lots of new tags, but are there any major structural changes in the way both of them work?

I'm sorry to bother the jsdoc community with such a long post. In my defence, once some of these questions are settled, our organisation plans to help out the community in terms of Templates, Plugins, Pull Requests and Issues. We were anyway making patches to jsDoc v2 before we found out its being superseded by jsDoc3.