Get our Newsletter!A while back, I posted about my struggle to find a good JavaScript documentation tool. Over the past week, I began exploring one more option which is very promising.
Ext-Doc is a JavaScript documentation tool which creates by far the best looking documentation. Created and maintained by several members of the ExtJS community, Ext-Doc outputs your documentation using a template mimicking the ExtJS documentation. The tool is compatible on both Windows and Mac/Linux (it runs off Java) and fairly easy to setup.
So far, I’ve only encountered three issues:
- The instructional Wiki on Ext-Doc site (hosted on Google Code) is simply terrible. It’s clear that the focus has been on developing the tool itself, but there’s close to zero documentation supporting it. If you need help, you have to search the ExtJS message boards.
- The documentation output by the tool cannot be viewed locally – it must be uploaded to a server as it relies on Ajax.
- The documentation tags are different from some of the other JS documentation tools
The first issue is obviously frustrating, particularly as the Java JAR file will hit errors and give you no reason why anything fails. Searching through the ExtJS forum and talking with the community has helped me get started, but this is a huge flaw and is (in my opinion) preventing Ext-Doc from being the defacto JavaScript documentation tool available. If they can get their Wiki up to date then this tool will certainly make an impact.
The second issue is actually pretty easy to work around on Microsoft Vista. Since Vista comes packaged with IIS7, you can simply tell the .BAT file to output the documentation to your local host’s root. This way, you can update and view your docs without having to copy/paste or FTP files to a web server.
Lastly, the tags used to document your JavaScript code are different in Ext-Doc than in JSDoc Toolkit (which is what I had been using). I don’t know if either tool is actually consistent with documentation standards in JAVA, but I wish that all of these JavaScript tools would use the same set of tags. It would make testing other tools much easier, and consistency in documentation is really important. Douglas Crockford (if you’re reading this), can we PLEASE get this discussion in front of the ECMA Standards board?
At the very least, I’m biased towards this new Ext-Doc tool (not really so new, actually) because I use ExtJS and I love their documentation. Once I get my tags updated, I think I’ll be very happy with this tool.
Well! I agree to the points as well as I disagree mainly for the first point.
Yes, i also had to google it for the documentation of it. But, when i observer the project at google, it is put into very simple words, which i skipped earlier. Infact there is a dedicated thread for it in extjs forum indeed (link : http://bit.ly/6J9JJp ). Which is the best way to share.
My first point (lack of solid documentation) is actually a bit out-dated. Not long after I wrote this post, I became a project member where my role is solely dedicated to improving the ExtDoc documentation Wiki.
Thus, the documentation for ExtDoc is better (though probably far from great). That ExtJS message board thread is very helpful as well… but it has 21 pages of quasi-random comments.
If you have any suggestions about the ExtDoc documentation Wiki, I’d love to hear them!