On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig
wrote:
You are right. I browsed some phobo's code and saw the
documentation, it looks clean and nice. The only exception is
std.algorithm which is full of macros and barely readable.
So where is that other macro code? The one that has
$(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed?
IMHO biggest issue is not inline documentation for functions but
more higher level stuff like http://dlang.org/arrays.html - it
was all in DDOC too last time I checked and changing anything
about it is hardly a pleasure. Inline documentations only suffers
when more pretty stuff like tables gets added.
One more fundamental issue with inline docs is not markup
language but lack of any simple way to inherit / refer existing
documentation entries. There is "ditto" but no "same as in base
method" or "same as for symbol X".
