[prev in list] [next in list] [prev in thread] [next in thread] 

List:       jedit-devel
Subject:    Re: [ jEdit-devel ] that first line in your javadoc comment is important!! Don't waste it!
From:       Jarek Czekalski <jarekczek () poczta ! onet ! pl>
Date:       2012-03-31 6:54:59
Message-ID: 4F76AA43.8030709 () poczta ! onet ! pl
[Download RAW message or body]

Alan, what you said about javadocs and the first line looks suspicious 
to Matthieu and me. I was hoping you could support your words with a 
single live example.

Jarek

W dniu 03/31/2012 08:46 AM, Alan Ezust pisze:
> My definition of a broken javadoc is one that has some text after the
> /** but none of it appears in the package summary for the short
> description.
>
> If you look at the package summary for any of jEdit's packages, such
> as the "gui" package,
> http://www.jedit.org/api/org/gjt/sp/jedit/gui/package-summary.html
> you will see a lot of empty rectangles where there should be short descriptions.
> Most of those you see online right now, are fixed because I made some
> tweaking of the javadoc comments.
>
> You will also notice I did something similar to a lot of the
> CommonControls classes.
>
>
> On Fri, Mar 30, 2012 at 11:16 PM, Jarek Czekalski
> <jarekczek@poczta.onet.pl>  wrote:
>> 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
>>> <chocolat.mou@gmail.com>    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<alan.ezust@gmail.com>
>>>>> 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
>>>>> jEdit-devel@lists.sourceforge.net
>>>>> 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
>>
>> ------------------------------------------------------------------------------
>> 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
>> jEdit-devel@lists.sourceforge.net
>> 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
-- 
-----------------------------------------------
jEdit Developers' List
jEdit-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/jedit-devel
[prev in list] [next in list] [prev in thread] [next in thread]