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

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

Il lun, 2004-01-12 alle 11:12, Eric Le Goff ha scritto:
> 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 ?
Sorry, I hadn't read the mail from Jeff: it's ok for the all in one
patch ;)
-- 
Luca De Rugeriis <pie...@li...>