Re: [java-gnome-hackers] Minor javadoc enhancement

[Eric Le G. <eri...@gi...>]

Luca De Rugeriis wrote:
>  [...]
> 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. 
Agreed. I had a quick look at java code with checkstyle and it seems 
that many javadoc are also out of date (missing @return , etc..).
If you like I could do some javadoc review and submit you a patch.

Would you suggest a globl patch for this, or one per package ? class ?


--Eric