[java-gnome-hackers] Minor javadoc enhancement

[Luca De R. <pie...@li...>]

I saw, in gtk-docs too, that there are little inconsistencies in the
description fields and in the @param fileds, like cap letter at the
beginning of a phrase or the period at the end.

I would suggest to follow a common line for this, so our javadocs will
look more professional:

The main descriptions of methods and classes should always use caps at
the beginning of periods and obviously periods at the end. They should
also contain links to every thing that can be linked.

Description of parameters and returned values are like minimal
statements, so the shouldn't begin with a cap and the should have no
period at the end.

I hope this is clear. I'm just talkin about the javadocs ;)
This is an example of what I was thinking:

	/**
	 * Sets the {@link ToolTips} object to be used for ToolItem, the text to be 
	 * displayed as tooltip on the item and the private text to be used.
 	 *
	 * @see ToolTips#setTip(Widget, String, String)
	 * @param tooltips the {@link ToolTips} object to be used
	 * @param tipText text to be used as tooltip text for ToolItem
	 * @param tipPrivate text to be used as private tooltip text 
	 */

As you see the description has caps and periods, while the parameters has none of them.
Also a link which points to the class you are in should be avoided. 
(for example I would not write {@link ToolItem} but simply ToolItem}.

What do you think? Old classes' javadocs could be fixed, for example, if
you open the class to take a view of the source, then you can quickly
fix the punctuation. 

Also, what about the @since and @author tags?
Are we going to use them? If so, I'll commit new classes with these tags
included, (and maybe fix some older one).

Sorry for the long mail, I know this is not vital, but it will make our
docs more consistent.

-- 
Luca De Rugeriis <pie...@li...>