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.ch...@gmail.com> >> 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@lists.launchpad.net >>> Unsubscribe : https://launchpad.net/~kicad-developers >>> More help : https://help.launchpad.net/ListHelp >>> > > _______________________________________________ > Mailing list: https://launchpad.net/~kicad-developers > Post to : kicad-developers@lists.launchpad.net > Unsubscribe : https://launchpad.net/~kicad-developers > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
