Wednesday, October 4th, 2006
Natural Docs: Better Javascript Doc
Category: JavaScript
, Utility
Jesse Kuhnert (or Dojo/Tapestry fame) wrote to us pointing to Natural Docs.
Using the utility from http://naturaldocs.org and about 10-15 minutes of slight adjustment to my javascript comments I was fairly easily able to produce this.
Keep in mind that this is only a very small sampling of the Tapestry javascript library, but it looks like a promising utility for many javascript libraries out there. It even has dhtml tooltips + searching :)
Time for some better docs?
4.2 rating from 14 votes
interesting - i’m considering using naturaldocs, too. i’m using jsdoc for javascript and phpdoc for php at the moment, but i’m not very satisfied. with it, especially because this both don’t integrate. one tool for all would be much better.
on the other hand: there are no native parsers for javascript and php in natural docs - so you have to rewrite all your sourcecode documentation - that keeps me from using naturaldocs at the moment.
[...] Publicado en Ajaxian [...]
if only those in the like of Dojo, Prototype and scriptaculous used this kind of documenting tool too… :)
Doxygen will probably outperform Natural Docs, simply because it reads all kinds of source code languages and has an established data format for representing “documentation”. HTML is only one of the ways you can render that data format.
And so there is a lot more support for doxygen in general. The best thing Natural Docs could do is to parse javascript (which it seems to be good at) and output data suitable for use by doxygen.
Jesse, would you be willing to share with us how you formatted this? I spent a few hours with this app tonight and it’s slick, but I can’t get my docs to work quite right.
Does any of you know if Natural Docs support prototype constructor? I would like my comments on initialize method to appear as comments on constructor function.
naturaldocs is real cool. there’s no un-necessary hassles. u get neat documentation really easy. no need to use special tags like doxygen and the comments need to be just as natural and readable as comments ought to be. great tool. no learning curve. can take almost any type of coding convention. really came in handy when coding in vxworks standard for embedded platform.
@Mot
NaturalDocs requires you to explicitly document your classes/functions. It won’t auto-generate documentation without descriptions like JSDoc does. The only thing I don’t like about it is the fact that you don’t use standard javadoc comments (eg/ @param).