Worst Phobos documentation evar!

[Adam D. Ruppe via Digitalmars-d]

On Tuesday, 30 December 2014 at 01:50:01 UTC, ketmar via 
Digitalmars-d wrote:
> D documentation WILL be bad until ddoc will start to understand 
> some markdown-like mostly macro-free markup language.

I honestly don't think the macros are the biggest problem though. 
I think a bigger deal is the lack of overviews.

Take a look here:

http://dlang.org/phobos/std_algorithm.html


There's some overview, and even a couple links. But the point 
about opaque types that are supposed to just work isn't easy to 
find.

Contrast it to what Microsoft wrote up for Windows:

http://msdn.microsoft.com/en-us/library/ms713499%28v=vs.85%29.aspx

There's conceptual overviews, real-world examples, and the 
references (which link back to the relevant concepts and 
examples).


std.algorithm could mention the concept of laziness, show 
examples of the opaque functions, have examples of the common 
(like seriously one of the most frequently asked questions I've 
seen) "how do I turn it into an array?", or show/explain how and 
why to avoid that.


That's mostly plain text that could be written up in the module 
explanation or as a separate page. I think that's more important 
than what macros are used.