java-gnome-hackers

[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...>

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

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.
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 ;)

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

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

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...>