We need better documentation for functions with ranges and templates

[Andrei Alexandrescu via Digitalmars-d]

On 12/15/2015 03:08 AM, landaire wrote:
> - Runnable examples would be *so* useful! They're present on the
> homepage, why can't the examples provided in the inline docs be runnable
> as well?

The runnable examples were first provided by nazriel (he's to be found 
around here and on IRC). He also started to expand runnable examples, 
but then got busy with other things. This would be a great project.

> - Linking types, functions, etc. in the function signatures would be
> great *if possible*. e.g.:
>
> bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, R2
> withThis) if (isInputRange!R1 && isInputRange!R2 &&
> is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) : bool));
>
> Make bool, isInputRange, typeof, and binaryFun all links to their
> definitions. If I don't know what "isInputRange" does, do I really have
> to go spend more time to figure out where it lives?

This is a good idea that would require changes to ddoc.

> - Add another line break between overloaded methods! Having no
> separation between lines makes things very difficult to sort out

This is easy. You need to figure out what separator ddoc introduces 
between overloads. "make verbatim" in dlang.org was conceived exactly 
for that kind of stuff.

> Here's an imgur album I created to show some suggestions for function
> signatures: http://imgur.com/a/njHKI
>
> - Dead links = compile error when compiling documentation? This was
> annoying when trying to find out more about OutputRanges. The only
> resource I found was on the std.range page in the tee definition, and
> the link was dead: http://dlang.org/phobos/std_range.html#.tee

There are a number of dead link detectors, online and offline. We just 
haven't integrated any although Vladimir was looking into it at a point. 
This would be a fine project to get into, too.

> - Link to where the code is implemented in Phobos at the time of
> compilation. e.g. clicking the actual name of "find" could link me here:
> https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498.
> More than once I found that reading the code was more useful than
> reading the documentation.

We already have a SOURCE macro for that I think.

> I find that I learn best by reading documentation. Go's documentation is
> phenomenal and it's very easy to follow and understand (yes, I realize
> this is kind of comparing apples to oranges in terms of complexity). I
> don't want to have to have to read documentation on understanding the
> documentation.
>
> I'm currently on winter break from university and would love to help
> contribute some of these changes if people think they're useful as well.

I suggest you start with the simpler stuff, such as better formatting of 
overloads. That'll allow you to find your way around the doc build and 
see what the macros are and what they generate. It'd be great if you got 
the verbatim build going, it's seldom used but very helpful. Make some 
css changes while at it. Then move into more involved stuff.

Overall doc building is a territory where there's plenty of easy-hanging 
fruit, and the satisfaction is high. I have a great time whenever I get 
into it, just less often than I wish.


Andrei