Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

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