On 29 December 2014 at 15:39, Walter Bright via Digitalmars-d <[email protected]> wrote: > On 12/28/2014 8:44 AM, Kiith-Sa wrote: >> >> It depends on the function being documented. For 'downcase', such blocks >> are >> overkill; > > > After doing it both ways for a while, I'm pretty convinced they are not > overkill even for trivial functions: > > 1. they lend an air of consistency and comfort to the reader > 2. they provide an anchor for automated tools which can extract the > information > 3. without such a block, I've found that I (and others, > http://dlang.org/phobos/std_algorithm.html#.sort) tend to omit descriptions > of 'obvious' parameters which are actually not obvious at all. > 4. a block can be styled in a custom manner
I'm super happy to hear this :)
