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