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 `` 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.DELETE 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 19 Dec 06._