On 2011/3/2 Dan McGee <dpmcgee@gmail.com> 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 */