On 2011/3/2 Dan McGee <[email protected]> wrote: > We will come across it moving on, but we should also pick a format we > plan to follow, as I've seen several: > 1) Put first line on /** line, everything else follows after a > newline. This is the most compact. > 2) Same, but newline and empty line after first line. > 3) Use @brief, then a empty line, then remaining text. Things also > seem to have spaces between every part (brief, summary, params). > 4) Compact but using @brief. > > I don't care- as I said, I'm letting you call the shots, but we should > try and pick one and stick with it and eventually retrofit everything > to work this way.
I vote for compactness (at least in .h files). So I'd say my preferred formatting is /** @brief Some description. * * @params param a parameter. * @return the result */ and when the description is verbose (like for the description of the confusing return types between depends, optdepends, replaces...) /** @brief Some description. * * A verbose explanation. * * @params param a parameter. * @return the result */
