Burning Chrome: XBL and javadoc

August 17, 2005

XBL and javadoc

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.
 */
  -->

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.

Posted by WeirdAl at August 17, 2005 10:47 PM

Comments

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="http://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.)

Posted by: Tobu at August 18, 2005 1:20 AM

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.)

Posted by: Nickolay Ponomarev at August 18, 2005 1:22 AM

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.)

Posted by: Roland at August 18, 2005 1:40 AM

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.

Posted by: beaufour at August 18, 2005 1:50 AM

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.

Posted by: hansen at August 18, 2005 2:36 AM

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.)

Posted by: Nico at August 18, 2005 3:09 AM

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.

Posted by: funTomas at August 18, 2005 4:05 AM

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.

Posted by: Simplex at August 18, 2005 6:13 AM

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".

Posted by: peke at August 18, 2005 11:29 PM

>(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.)

Posted by: Nickolay Ponomarev at August 19, 2005 12:58 AM

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.)

Posted by: peke at August 19, 2005 6:31 AM

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).

Posted by: peke at August 19, 2005 10:35 AM

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).

Posted by: peke at August 23, 2005 1:50 PM

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?

Posted by: Joe Hughes at March 25, 2006 11:45 PM