Re: [ jEdit-devel ] that first line in your javadoc comment is important!! Don't waste it!

[Jarek C. <jar...@po...>]

Alan, could you show an example of invalid javadoc?

Jarek

W dniu 03/30/2012 06:58 PM, Alan Ezust pisze:
> Interesting, I didn't need to touch that class, because it already
> showed up in the package summary javadocs. I am not sure why that one
> did but  none of the ones I changed had short descriptions that
> javadoc was able to find.
>
> If it ain't broke, don't fix it.
>
> There are other rules that javadoc can use to find the short
> description, if it is easy
> for javadoc to figure out. I suppose that class satisfies one of them.
>
>
> On Fri, Mar 30, 2012 at 1:30 AM, Matthieu Casanova
> <cho...@gm...>  wrote:
>> Hi, are you sure ?
>> I just tried with common.gui.JMouseComboBox
>>
>> it's javadoc starts like this
>>
>> /**
>>   * This is a combo-box that allows listeners to be informed of mouse
>>   * entered and mouse exited events.
>>   *
>>   * Note that other mouse events besides MOUSE_ENTERED and MOUSE_EXITED still
>>
>> and
>> This is a combo-box that allows listeners to be informed of mouse entered
>> and mouse exited events.
>> seems to be used as short description of the class when looking at the
>> javadoc of common.gui package.
>>
>> The short description here stops at the first .
>> If I remove the . after event the short description continues until the next
>> dot.
>> Or are you talking about another place ?
>>
>> Matthieu
>>
>> 2012/3/29 Alan Ezust<ala...@gm...>
>>> Because it is the "short description" and is what is extracted in the
>>> table summaries of the javadoc program.
>>> If you look at the javadocs for CommonControls 1.3 versus what is in
>>> the SVN trunk, you'll see that there were a lot of empty rectangles
>>> before, and now there are not.
>>>
>>> That is because I put something into the first line immediately after the
>>> /**
>>>
>>> /** Short Description
>>>   *
>>>   * Long Description Line1
>>>   * Long Description Line2
>>>   * Long Description Line3
>>> */
>>> class MyClass extends Blah1 implements Blah2 {
>>>    ...
>>> }
>>>
>>>
>>> Please, everyone, get into the habit of using it! Not just for core +
>>> plugins, but for all your code.
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> This SF email is sponsosred by:
>>> Try Windows Azure free for 90 days Click Here
>>> http://p.sf.net/sfu/sfd2d-msazure
>>> --
>>> -----------------------------------------------
>>> jEdit Developers' List
>>> jEd...@li...
>>> https://lists.sourceforge.net/lists/listinfo/jedit-devel
>>
> ------------------------------------------------------------------------------
> This SF email is sponsosred by:
> Try Windows Azure free for 90 days Click Here
> http://p.sf.net/sfu/sfd2d-msazure