[phobos] Split std.datetime in two?

Jacob Carlborg doob at me.com
Thu Feb 10 11:06:22 PST 2011


On 10 feb 2011, at 11:46, Lars Tandle Kyllingstad wrote:
> I don't necessarily think that the documentation for std.datetime (or
> any other large module) needs to be split over several pages.  My main
> gripes with the current documentation are:
> 
> 1. The table of contents at the top sucks.  It's just one big lump of
> text, and it's impossible to see whether something is a free function, a
> member function, a type, an alias, an enum, etc.

Why not use CandyDoc? Originally from here: http://www.dsource.org/projects/helix/wiki/CandyDoc
It has a package tab, a list of all packages and modules, basically what's now in the left side menu. The other tabs is the outline tab which lists all declarations in the currently selected module. BTW Tango uses a modified version of CandyDoc.

> 2. The documentation only uses indentation to indicate the relationship
> between the different elements.  Look at the documentation for
> DateTime.fromISOString(), for instance.  You have to do a fair bit of
> scrolling to figure out whether it is a free function or a member
> function, and of which type it is a member.
> 
> 3. It is not possible to impose any structure on the documentation,
> beyond the one given by the code.  In the recent discussion about the
> std.algorithm docs, Adam Ruppe suggested a Tag: section, so you could
> tag an std.algorithm function with 'searching', 'set operation',
> 'sorting', etc.  That would probably do wonders for std.datetime as
> well.
> 
> Fixing these issues would go a LONG way in improving the documentation.
> (And it seems Andrei and Adam have both been working on this lately.)
> 
> -Lars
> 
> 
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos

-- 
/Jacob Carlborg



More information about the phobos mailing list