On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu
wrote:
Let's crowdsource the review. Please check the entries linked
from here: http://dlang.org/library/index.html.
Andrei
I think there needs to a clear separation between the end of the
overview (e.g. the cheat sheet in std.algorithm) and the rather
arbitrarily organised content beneath. A big header saying "API
Reference" or similar would do the trick.
I guess it makes sense in a way, but should an end user care that
std.algorithm.map happens to be written as a function nested in a
template and std.algorithm.find is a function template? I'm not
sure.
The "name" column in the variable reference tables is often far
too narrow.
It is *much* harder to get the general feel of a module in the
new format, unless it has a comprehensive overview. Previously I
would just scan down the page, seeing which symbols had more
documentation and examples (probably major entry points to the
API), quickly gaining context by having glanced at things on the
way through. Now I'd have to go through symbols individually,
without context, by laboriously clicking on links. Awful.
Overall it's a good idea, but while it will make std.algorithm,
std.range and some other well-documented modules with extensive
summaries and tables easier to use, it makes less well documented
modules even worse than they were before.
