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
