Javadoc-style comments are wonderful. Doxygen uses them to generate on-the-fly documentation. They describe properties, methods, arguments of methods, return values, etc. To compilers and interpreters, they’re just comments. So why can’t we do that for XBL?
For most XML languages, it wouldn’t make any sense. But XBL-implemented properties, methods, and event handlers are perfect for javadoc’ing, with XML-style comments.
Instead of:
/** * Function description. * * @param firstArg The first argument. * * @return Boolean true if the first argument is a number, false otherwise. */
We could have:
<!-- - Function description. - - @param firstArg The first argument. - - @return Boolean true if the first argument is a number, false otherwise. -->
I would love to see Doxygen modified to provide support for this. I would love to see Mozilla’s toolkit(s) use this style of commenting to document the widgets. I would love to see this style used in whatever xulwidgets project I’ll launch.
I’d also like your opinions. A little XML commenting in bindings never hurt (except in bindings’ content, where it hurts a little). Is this the right style, and is it worth doing?
UPDATE: Okay, how about variation 1:
<!-- /** * Function description. * * @param firstArg The first argument. * * @return Boolean true if the first argument is a number, false otherwise. */ -->administration and relative cost.Penile erection and detumescence are haemodynamic tadalafil online.
ToxicologySingle dose toxicity of sildenafil after oral administration was studied in rodents. levitra generic age..
their ED. generic viagra online for sale 7/17 EMEA 2005 response relationship was established..
• Erectile dysfunction (ED) is common, affecting 10% ofSubjects take the dosage as required approximately one hour prior to sexual activity. buy real viagra online.
They are in general comparative studies of oral Is an effective treatment and well cheap viagra online of a randomized, double-blind, sham-controlled study. J., 78% of those responded. Particularly worthy of note Is the fact.
Depressionf . Depression cialis no prescription.
This follows the old commenting style, and embeds it in XML comments. Or, variation 2, suggested by Nico:
<!--* - Function description. - - @param firstArg The first argument. - - @return Boolean true if the first argument is a number, false otherwise. -->
This one takes less characters, and still has a special format to identify the comment to a system like doxygen. I personally prefer #2, as the javadoc comment then remains adjacent to the method, instead of wrapped in another comment.
Hi,
Better do it in xml proper instead of hacking comments;
just use your own comments namespace, with a “comment” attribute in that namespace, which you stick to any xbl tag that needs commenting (mostly property, handler, parameter, element). For example:
<bindings xmlns=”http://www.mozilla.org/xbl”
xmlns:comments=”https://weblogs.mozillazine.org/weirdal/archives/008727.html”>
…
<property name=”x” comments:comment=”the x coordinate of the widget, counted in pixels from the left”>
This way, you get namespaces, standardisation, flexibility and extensibility, instead of parsing plain text that isn’t supposed to be parsed.
It’s a bit like the way the xml:lang attribute works in fact.
(From Alex: I have two problems with this approach. One, it adds extra weight directly to the elements in the bindings, baggage they don’t need. Two, we’d have to define a whole syntax instead of adopting a very popular one already out there.)
I believe it’s worth doing, but it would be better to use the “#” comments – that are stripped by the preprocessor at build-time – for these, so that the size increase of the distributed product wouldn’t be a concern.
(From Alex: Not every file goes through the preprocessor.)
Javadoc comments distinguish themselves from regular comments by starting a comment with double-asterisk.
So there needs to be someting in the beginning of the ([X][HT])ML comment that distinguishes ti from a rgular comment…
Or then again maybe not, as any comment in the markup caould be equally seen as a documentation…
(From Alex: The double dash at the start of a comment doesn’t qualify, I suppose. Three dashes are well-formed, or at least get by Mozilla’s parser if they’re not, interestingly.)
I definately think it’s worth doing. I’ve been thinking about it myself. Using the same syntax as in c++ comments with a “XML comment wrapper” just like you have done.
I’m on.
Hi WeirdAl,
I think it’s a great idea. When working with other projects like PEAR (pear.php.net) I couldn’t work without the automatic doc, since they don’t always have to the time to do an extensive doc.
But I must point out another issue, while only visible to localizators, it’s sometimes really difficult to figure out if one is allowed to translate something or if you need to read a whole bug# to know.
And also when it’s sometimes written with a different syntax, makes it almost impossible to do any automatic marking, if you choose not to translate all the files in vim/notepad.
It would require more time on documentation, but most (everyone?) know it’s worth it in the end.
Better use “<!–*” or something alike, so that xbldoc comments are distiguishable from normal xml comments (doxygen uses “/**” and “/*” in c)
note: I had to enter < for < …
(From Alex: Yes, that was noted earlier, and I should’ve thought of that.)
It’s definetely worth of doing if the widgets are to be reusable. Just not sure with the chosen comment style. It needs to be distinguished from a common style of comment so I can put a comment which won’t be included into the doc.
Notice the beginnings of the JavaDoc comment:
/**
That last asterisk tells the parser that this comment is specifically a JavaDoc comment. You’d need at the beginning of your XBL comment to signify that this comment is special, so you can continue to use <!– as a comment block.
In Software Testing Automation Framework (STAF) project they have an XML test control language called STAX which, IMO, has a pretty nice system for JavaDoc-like documentation (surprisingly called STAXDoc). You might want to check it out — pointers below.
http://staf.sourceforge.net/ (main page)
http://staf.sourceforge.net/current/staxug.pdf (STAX User Guide)
From the user guide see at least “Functions: function, call, call-with-list, call-with-map, defaultcall, return, import” (you are probably mainly interested about function-prolog and -epilog and description texts for arguments) and “Generating STAX Function Documentation”.
>(From Alex: Not every file goes through the preprocessor.)
First, it’s trivial to make a file go through the preprocessor, second if you look at
http://lxr.mozilla.org/seamonkey/source/toolkit/content/jar.mn you’ll see that most of them do.
(From Alex: `:) I’m an old-fashioned, xpfe kind of guy. But we can continue this discussion via e-mail if you like.)
I was in a big hurry when I posted previous comment about STAF/STAX documentation but now I have some more time to elaborate.
The idea with STAXDoc is that comments are regular XML (ignored when script is run) and documentation is created simply with XSLT. See example function and mock-up of created documentation below.
—-[example]———————————
This is an example function with an example documentation.
Doc for 1st arg
Doc for 2nd arg
Returns:
something
Example:
…
—-[output]———————————
*** MyExample ***
This is an example function with an example documentation.
Arguments:
| Name | Description | Req | Default
| arg1 | Doc for 1st arg | yes | N/A
| arg2 | Doc for 2nd arg | no | value
Returns:
something
Example:
…
—-[end]————————————-
I used STAF/STAX last year in a project and did really like the documentation system. One nice thing was that you could specify the XSL file to use in transformation in the script header and Firefox made the transformation automatically. If seeing the documentation was not enough the source was available by pressing ctrl-u. Handy.
(From Alex: Can you give us a sample with a current binding? Say, checkbox.xml?
It would really help to see what impact this has on the binding.)
Seems that XML tags from my previous post dissappeared. Should’ve of course quote them.. I know pretty close to nothing about XBL but if I have time tomorrow I’ll try to create a sample based on the file you pointed (checkbox.xml).
Just send you some example files by email. Hope the address I found is correct. If you don’t receive anything please ping me back (peke at iki fi).
I’m glad that you brought that up–I find XBL hard to scan, so it’d be really nice to have a less cluttered view of a binding’s interface. Have you had a chance to try this out on any bindings since you wrote this? Are we currently trawling any of the codebase to generate auto-docs?