java-gnome 4.1.3, released 4 May 2013
About
Overview, News
Documentation
Tutorials, API, and Hacking
Download
Binaries and Source
Interact
Mailing Lists, IRC, and Reporting Bugs

doc/style/Documentation

Style guide: Documentation

Text files

Documentation such as design documents and files like this one are almost always viewed in terminals using pagers like less. It does no one any good if the paragraphs run off into the netherworld off the right of the screen somewhere.

Therefore, all textual documentation should be word wrapped at 78 characters, the same as for JavaDoc comments. If you look at the bottom of this file, you’ll see a vim modeline which will takes care of it for this file.

The exception, of course, is source code fragments. If they run on past the 78 character mark, then so be it it.

JavaDoc

Don’t bother putting class names in <code> spans. You’d never get anything done.

There’s no reason to @link ever single class name either. JavaDoc is already full of cross references. Only put a @link tag in when you really think that someone should follow the link to the doc snippet you’re pointing at.

Getters and setters are a bit obvious. If the single sentence you write for getLabel() is “Get the text of the Label on the Button” and the method returns String, then there’s not much need to put a @returns clause in. If unusual things happen in parameters or return values (for example null is an acceptable argument, or a return of -1 indicates success) then definitely explain it in a @param or @return clause!

Please take the trouble to write out a bit of supplementary text for a link so that you positively control what text appears. Otherwise you can end up with fully qualified class names and all sorts of other ugliness which distract from the flow of the paragraph. For example, if you just do:

/**
 * For more details, see {@link org.gnome.gtk.Button#setLabel(java.lang.String)}.
 */

You end up with “For more details, see org.gnome.gtk.Button.setLabel(java.gnome.String).” Bleh! So try adding a bit of extra text to make it more natural:

/**
 * For more details, see Button's {@link org.gnome.gtk.Button#setLabel(java.lang.String) setLabel()}.
 */

This will render as “For more details, see Button’s setLabel().” Much better.

As a matter of consistency, if you are referring to a static method, say:

Gtk.init()

but to talk about an instance method, use the possessive, eg:

Button's setLabel()

Obviously the whole point of java-gnome is to wrap GTK and the other GNOME libraries. Unfortunately, however the doxygen documentation for GLib, GTK and friends, while extensive, is quite inappropriate for someone brand-new to GTK or {Linux,Solaris}. Therefore, in order to achieve the criterion of Approachability that we defined as our primary goal, considerable massaging and indeed complete rewriting is necessary. Use a friendly, casual, and colloquial style… and don’t forget an example snippet! Methods like Widget’s show(), the entire Button class, and the signal Window.DeleteEvent are all good examples.

Finally, where it is appropriate to discuss how our implementation varies from conventional GTK practise, use a paragraph all in italics at the end of the class’s JavaDoc to explain the divergence or how java-gnome is implemented. The comment at the top of org.gnome.glib.Object is a pretty good example of this. But other than these rare observations, don’t refer to the translation, native, JNI layers or the native library [call] itself at all! Whenever possible, we want the implementation details of java-gnome to be invisible. They’re not public after all!

Spelling

And for super bonus points, run a spellchecker over any documentation you contribute. Yes, on code too!

We use LANG=en_CA around here, but don’t worry if your written English isn’t very strong or if you speak American. What matters is that you’re contributing and a native English speaker like myself will be more than happy to fix it up.

An aspell word list is included at the top of a checkout in the file .aspell.en.pws containing all the custom usages from both documentation and Java source code. To use it to spell check Button.java, for example, try:

$ cd src/java/org/gnome/gtk
$ aspell -x -p `bzr root`/.aspell.en.pws -c Button.java

Originally written by Andrew Cowie 2 Dec 06. Last modified 2 Jan 09.

Contents copyright © 2006-2011 Operational Dynamics Consulting Pty Ltd, and Others. See AUTHORS file and source code history for the various files comprising this site for full details. This page was generated from a text document! We use John Gruber's Markdown syntax as ported to PHP by Michel Fortin. See MARKUP for details