Human unreadable documentation - the ugly seam between simple D and complex D

[H. S. Teoh via Digitalmars-d]

On Thu, Mar 26, 2015 at 11:05:28PM +0000, Israel via Digitalmars-d wrote:
> On Thursday, 26 March 2015 at 21:36:56 UTC, rumbu wrote:
> >On Thursday, 26 March 2015 at 19:45:19 UTC, Alex Parrill wrote:
> >>On Thursday, 26 March 2015 at 19:32:53 UTC, Idan Arye wrote:
> >>>...snip...
> >>
> >>So tl;dr; make the template constraints in ddoc less prominent?
> >>
> >>The "new library reference preview" under Resources seems to already
> >>have this (example:
> >>http://dlang.org/library/std/algorithm/searching/starts_with.html)
> >
> >This will not solve the readability problem:
> >
> >- what is a range?
> >- what is a needle?
> >- what is a predicate?
> 
> Wouldnt that just be "Further documentation" for advanced programming
> concepts?
> Only simple easy to understand examples are needed to begin with.
> 
> It should flow like a tree.

There has already been a recent push to add hyperlinks in Phobos docs
whenever "input range", "output range", etc., are mentioned, to the
definitions of these terms. Well, currently they point to the
isInputRange, isOutputRange, etc., templates in std.range.primitives,
which may not be the best introduction to the concept of ranges, but at
least it will tell you which methods must be supported by these ranges.

Perhaps there should be a glossary page on dlang.org where these terms
can link to, instead.


T

-- 
The richest man is not he who has the most, but he who needs the least.