[phobos] Split std.datetime in two?

[Steve Schveighoffer]

Agree 100%.  Leave the module as-is and let's improve the doc generator.  I don't think we should design the functionality of code around documentation issues.

-Steve



From: Michel Fortin <michel.fortin at michelf.com>
To: Discuss the phobos library for D <phobos at puremagic.com>
Cc: 
Sent: Thursday, February 10, 2011 8:03 AM
Subject: Re: [phobos] Split std.datetime in two?

Le 2011-02-10 à 0:54, Jonathan M Davis a écrit :

> I do have one concern however. As there's a fair bit of functionality in there, 
> there's a lot of documentation, and I'm afraid that the documentation may be a 
> bit overwhelming to someone trying to figure out how to use std.datetime. On the 
> whole, everything in there is quite easy to use, but there's a lot of it.

I agree that the documentation isn't very well structured; std.datetime is hardly the only module with this problem.

I disagree about restructuring the code if the goal is only to make the documentation better. The right solution is to improve the documentation generation, not to contort the code to fit a particular documentation structure. Let's ask ourself how we want the documentation to be, then lets look at how we can achieve that.

Creating a table of content sorted by task (like Andrei did for std.algorithm) looks like a good start. Another idea to address the nesting problem could be to collapse the nested declarations with a show/hide javascript button to avoid having nested declarations you don't know they belong to what (if you've explicitly disclosed some content, you should know what it is). Perhaps it'd also be nice if things could be split on multiple pages, but I'm not sure on what criterion.


-- 
Michel Fortin
michel.fortin at michelf.com
http://michelf.com/



_______________________________________________
phobos mailing list
phobos at puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos


      
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/phobos/attachments/20110210/412510fb/attachment-0001.html>