On 2/10/11 7:59 AM, Steve Schveighoffer wrote:
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.
Same here. There are two additional options we have:
- Reduce the size of the documentation. Jonathan is not the tersest guy
I know, and there is a fair amount of repetitiveness in the
documentation. For example DateTime opBinary comes with a full table
with four rows and five columns that conveys the simple fact that adding
or subtracting a duration to a DateTime yields a DateTime. That and many
other tables have identical rows (I think it's a cut and paste error;
the idea might have been to swap the order of arguments, yet _still_ a
table is not justified there).
- Write a separate document about dates and times in the form of a
manual, and reduce the size of the documentation proper. Insert
references to the manual.
Now that the topic came about I have serious concerns about code and
functionality density of Phobos going forward, and that I promised
myself to be extra hawkish about it.
std.datetime has 34219 lines, which accounts for over 26% of the entire
Phobos size. If Jonathan will (as he promised, I didn't forget :o)) fix
line sizes to conform to 80 columns, then std.datetime will become 40961
lines, or straight 30% of Phobos.
(This might have to do with the increase of "hello, world" that was
noted by some people on the compiler list.)
I understand there are factors that contribute to that: date and time
manipulation is a bulky endeavor, there's a ton of unittests, and
there's a lot of documentation. But at a level I find it difficult to
digest the fact that in sheer numbers date and time manipulation
accounts for 30% of Phobos. As a comparison point, std.algorithm does
arguably a lot of work, has adequate documentation, and has unittest
coverage at 95%, yet does all that in a "measly" 8027 lines.
Now say we added std.unittests exactly as proposed. It has 2247 lines,
which puts it at 73 percentile in terms of LOC in Phobos - just below
std.stdio and above workhorses such as std.random, std.variant, and
std.concurrency itself. Again, I find it difficult to convince myself
that a few unittest support functions and their paraphernalia need that
much real estate.
Andrei
_______________________________________________
phobos mailing list
[email protected]
http://lists.puremagic.com/mailman/listinfo/phobos
