On Tue, Dec 30, 2014 at 03:20:30PM +0000, Adam D. Ruppe via Digitalmars-d wrote: > 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.
Yeah, one of the most glaring defects of ddoc is the inability to generate tables of contents and/or indices. This forces you to manually maintain TOCs, navigation bars, etc., which is a royal pain and prone to quickly falling out-of-date as the code changes. There have already been a number of Phobos PR's that have slipped through without proper updating of the manually-maintained tables of links at the top of the module docs. Being able to automate this, or at least give a compiler warning when things don't match up, would be GREATLY appreciated. > 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. PR, please. ;-) This is a lack in content, that no macro system can make up for, as you said. T -- People say I'm indecisive, but I'm not sure about that. -- YHL, CONLANG