Are there any plans on introducing something similar to Javadocs in Dojo (or does something like this already exist)? It could serve as the basis for the API documentation.
Example...
/**
* Class description here.
* @author: foo
*/
dojo.declare("my.classes.bar", my.classes.foo, {
/** This is some data. */
someData: [1, 2, 3, 4],
/**
* Constructor description here.
* @param node: A DOM node.
* @param args: Arguments to mixin with this class.
*/
constructor: function(node, args) {
...
}
});
* Class description here.
* @author: foo
*/
dojo.declare("my.classes.bar", my.classes.foo, {
/** This is some data. */
someData: [1, 2, 3, 4],
/**
* Constructor description here.
* @param node: A DOM node.
* @param args: Arguments to mixin with this class.
*/
constructor: function(node, args) {
...
}
});
we already have a system like this
See the documentation section of the style guide:
http://dojotoolkit.org/developer/StyleGuide#Documentation
Output from our inline documentation in this format is currently at:
http://redesign.dojotoolkit.org
I think you'll find the documentation style is both more readable in code and that the output much more closely matches JavaScript's semantics than other tools (such as jsdoc).
Ah...I see it now.
I had seen these comments in the code, and it looked like some convention was being used, but I hadn't seen the style guide yet, so I didn't know for sure.
My only concern is that unless you happen to know the names of the keys used for the documentation, it's difficult to tell the difference between the doc keys and commented out properties. It's also difficult to differentiate between documentation comments and other comments.
e.g. ...
// summary: This is my class
//
// description: This is the description of my class
// someCommentedOutField1: "xxx",
// someCommentedOutField2: "xxx",
// Some random comments that I've inserted into my code.
This could be improved by adopting Javadoc-style comments...
/**
* summary: This is my class
*
* description: This is the description of my class
*/
// someCommentedOutField1: "xxx",
// someCommentedOutField2: "xxx",
// Some random comments that I've inserted into my code.
I would think that...
...a quick perusal of the code, and encountering the style:
...compared to this:
...is enough of a difference (particularly in the placement of the original comments) to see that one is a consistent documentation-type tag, and the other is a legitimate comment. However, giving the benefit of the doubt, I would hope that we are consistent enough with our documentation comments so as to help make it clear, as you look over the codebase, what we use for the documentation and what we don't.
We've been over the entire "why don't you use JavaDoc style comments", and the short answer is that we found it to be sorely lacking in many ways (not in the least being the lack of ability to actually understand a regular JS idiom without making it look and work like Java--and taking a huge perf hit in the process).
I don't have a problem with the syntax.
To be clear, I don't have a problem with the syntax. I simply believe that using /** */ instead of // to demarcate doc comments makes it easier to tell what's a doc comment and what's a regular comment. (And as a side note, it seems to me that using /** */ could be more flexible, since the doctool could simply capture all /** */ comments within a function, and not just rely on forcing the comments to be at the beginning of the comment block.)
The example I gave above is only one example. Another area of confusion would be if you insert non-doc comments immediately after a doc comment. Does the non-doc comment become part of the summary?
// Here's a random comment that has nothing to do with the summary tag above.
It may or it may not. The point is that unless I'm intimately familiar with how the doctool works, I cannot tell for certain.
Or what if I want to embed personal comments in my code at the beginning of a function block, which would seem to be the logical place for putting something like a TODO comment...
// summary: some text goes here
On the other hand, it's plainly clear what's a doc comment, and what's a non-doc comment below...
/**
* summary: some text goes here
*/
// Here's a random comment that has nothing to do with the summary tag above.
My $.02
I just double-checked...
...and apparently our doc tool doesn't really care if you wrap the doc comments using /** or //; I think we've just been using the other style as a stylistic thing more than anything else. That means that in theory, we can change all of what we've been using for doc comments to the JavaDoc style without any adverse effects.
Of course, the other issue is actually going through and changing all of them :) There's a lot of source code in the repo, so it'd take a while to change them all that way. But I'll suggest it at the next Dojo meeting. I doubt everything will get changed by the time of the 1.1 release but it's definitely possible to do it by 1.2.
We *do* have one structure that we use to document keyword argument objects, and I don't think that's going to change any time soon; but that one should be immediately apparent on looking at the source (begins with /*=====).
Cool!
That's great!
One last question....when using /**, does the doctool allow you to specify '*' at the beginning of each line?
e.g....
* xxx
* xxx
*/
(If not...a simple regular expression, like replace(/\n\s*\*/g, "\n"), could get rid of them)
btw...
...you can watch the in-progress development of the new Dojo API documentation tool at http://redesign.dojotoolkit.org . Eventually (sometime soon, I hope) it will be moved to a more permanent address, but this is where pottedmeat (the author of the doc system) and I (author of the themes for dtk) have been pooling our staging efforts.
Are you familiar with Python?
So there's an allegory to the syntax we use in Python's automated documentation formatting. The convention is that the first contiguous comment block inside a function defines the docs for it, and we follow that convention in our doctool. Like any convention, changes to expectations carry a cost and are uncomfortable at first, so I don't expect someone who likes javadocs to *immediately* see the value in our syntax, but I think that as you start to use the syntax you'll see it's advantages and that it will become very clear what's what in short order.
Regards
See comment above.
I have to admit that although I've done some Python scripting, I've never embedded doc comments in it before.
However, the conventions being used are fine with me and easy to understand. My only suggestion is that using /** */ instead of // to demarcate doc comments makes the code easier to read, since it makes it blatantly obvious what's a doc comment and what's a regular comment.