Ready to make page-per-item ddocs the default?

John Colvin via Digitalmars-d digitalmars-d at puremagic.com
Wed Jan 7 04:26:29 PST 2015


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.


More information about the Digitalmars-d mailing list