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

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

Luca De Rugeriis wrote:
> 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.
> 
> Great! but be aware that many liks are broken because of yet
> unimplemented classes/methods, so you have to guess what to do case by
> case.
> 
> 
>>Would you suggest a globl patch for this, or one per package ? class ?
> 
> If you have a chance, it's better to have separated ones.
> 
> Note also that your work on translation is far more important ;)
> 
OK, I will first get a final effort to the french translation. I will 
save these javadoc minor enhancements for later (as they are less 
important).

I started with the GNOME-tutorial translation , so that it helps me to 
get into this project at the same time ;)

I hope to send you the first french doc very soon.

Cheers

--Eric