std.datetime is too big

[Regan Heath]

On Mon, 07 Nov 2011 12:22:24 -0000, Jacob Carlborg <doob at me.com> wrote:
> On 2011-11-07 11:53, Regan Heath wrote:
>> On Mon, 07 Nov 2011 09:20:55 -0000, Jacob Carlborg <doob at me.com> wrote:
>>
>>> On 2011-11-05 19:33, Jonathan M Davis wrote:
>>>> The number one thing that _I_ would like to see which would make
>>>> std.datetime
>>>> much easier to digest would be for ddoc to be fixed so that the
>>>> anchors that it
>>>> generates actually represent the code's hierarchy. For instance,
>>>> right now,
>>>> the year functions for Date, DateTime, and SysTime all get the exact
>>>> same
>>>> anchor - #year - so you can't link to each individual function. It
>>>> needs to
>>>> be generating anchors more along the lines of #Date.year,
>>>> #DateTime.year, and
>>>> #SysTime.year. That way, I could organize the links at the top of the
>>>> documentation and make it so that they're actually informative and
>>>> help you
>>>> understand the module instead of confusing you.
>>>>
>>>> - Jonathan M Davis
>>>
>>> I think that the jump-to list should only refer to top level elements
>>> and not methods inside classes.
>>
>> Then, the top level elements could have (collapsible) jump-to lists for
>> their members.
>
> I think it should depend on the type.

Definitely.

> I don't see a need for enum members in the jump-to list. Possible not  
> struct/class fields either. Take a look at this for example:  
> http://d-programming-language.org/phobos/std_net_isemail.html
>
> The useful functions and types are lost in the jump-to list consisting  
> mostly of enum members.

Agreed.  In this case the top of the page should only have 1 link for  
"EmailStatusCode".  The rest can be listed below that.  If someone is  
looking for a particular value, they're going to CTRL+F anyway.

>> The M$ style for documentation is quite easy to use/navigate. They tend
>> to restrict themselves to a single class per page, for example:
>> http://msdn.microsoft.com/en-us/library/system.net.sockets.tcpclient.aspx
>>
>
> C# and especially Java have only one class per file, this is not the  
> case for D and certainly not for Phobos.

Sure, but that doesn't have to dictate the number of web pages we use to  
document D modules.  I mean, std.datetime may be 1 file, but contain 5  
classes (for example) and we can still choose to have 5 (or more) web  
pages, one for each class and all linked from a std.datetime top level  
page.  Basically we want documentation that is easy to navigate, how it's  
done is completely up to us.  I think multiple pages, and collapsible  
sections will make pages easier to navigate in general, and a consistent  
layout will aid in understanding also (for experienced readers) but,  
common sense can overrule this where appropriate - i.e. no sense having a  
collapsible section with a single line in it - for example.  It would be  
nice if DDoc had the ability to make that decision, somehow - it might,  
I've not used it at all so far so I have no idea.

-- 
Using Opera's revolutionary email client: http://www.opera.com/mail/