Enhancement: issue error on all public functions that are missing ddoc sections

[Jonathan M Davis via Digitalmars-d]

On Thursday, March 19, 2015 22:27:33 deadalnix via Digitalmars-d wrote:
> On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:
> > On 3/19/2015 2:40 AM, deadalnix wrote:
> >> And I'm sorry, but if most function require DDoc, your code
> >> probably sucks quite
> >> badly and some renaming should be considered.
> >
> > I've never seen any code that self-documented "why".
>
> Indeed, that is why comment are useful. If all your method
> require a why, you probably should consider refactoring instead
> of adding comments all over the place.

There are plenty of functions that require documentation - especially when
they're more powerful. This is especially true when talking about free
functions rather than member functions. And having documentation for stuff
like what exceptions a function throws can be quite valuable even if the
function's primary functionality doesn't need much explanation. I think that
it's safe to say that most functions need at least minimal documentation.
However, I completely agree that there are a number of functions (especially
property functions and other types of simple accessors) which don't need a
detailed explanation, and having both a main comment on them and a return
and/or param comment on them is redundant and just noise.

So, I fully expect that requiring a return comment or a comment per param
will quickly result in documentation comments being overly verbose. That
being said, most functions do need some sort of documentation, and there are
definitely some functions that will need both the return and param comments
(especially the sort of stuff that goes in std.algorithm).

- Jonathan M Davis