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.
