kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

I'm going to side with Chris on this issue.  Using a first sentence for
the brief description, followed by an empty line, and then an optional
detailed paragraph is certainly much more readable than using the
doxygen keywords.

On 3/22/2017 12:14 PM, Chris Pavlina wrote:
> I really hate @brief and @details. Doxygen can do that automatically,
> making the brief docstring the first sentence and the details one the
> whole text. It makes for a doc comment that is much more readable in the
> header itself, which is honestly how I read them most of the time.
> 
> On Wed, Mar 22, 2017 at 11:11:35AM -0500, Jon Evans wrote:
>> Hi Chris,
>>
>> I agree with this and would also suggest that there are more Doxygen tags
>> we can use if desired.
>> In fact, I use a plugin for my editor that generates Doxygen templates
>> automatically if I type "/**<Enter>" above a line of code:
>>
>> /**
>>  * @brief [brief description]
>>  * @details [long description]
>>  *
>>  * @param aColor [description]
>>  * @return [description]
>>  */
>>
>> There is also the "@see" tag which is quite useful
>>
>> -Jon
>>
>> On Wed, Mar 22, 2017 at 10:41 AM, Chris Pavlina <pavlina.chris@xxxxxxxxx>
>> wrote:
>>
>>> Hi all and mostly Wayne,
>>>
>>> I notice that a lot of our older documentation comments redundantly list
>>> the name of the function they document:
>>>
>>>     /**
>>>      * Function IsVoid
>>>      * @return true if the field value is void (no text in this field)
>>>      */
>>>     bool IsVoid() const
>>>
>>> I don't see any purpose for this redundancy - Doxygen doesn't use it,
>>> the formatted documentation actually looks better without it. It seems
>>> unnecessary to me, and a bit ugly: https://misc.c4757p.com/isvoid.png
>>>
>>> (Not to mention that this is a method, not a function ;)
>>>
>>> I'd document this method thus:
>>>
>>>     /**
>>>      * @return true iff the field value is void (i.e. has no text)
>>>      */
>>>     bool IsVoid() const
>>>
>>> Is there any reason to keep these?
>>>
>>> --
>>> Chris
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~kicad-developers
>>> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~kicad-developers
>>> More help   : https://help.launchpad.net/ListHelp
>>>
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>