On 2011-11-05 08:58, Somedude wrote:
> Hello,
>
> I've been lurking for a while here and I really appreciate all the work
> that is done on D and Phobos. This is a fantastic language and a great
> little community. So I don't want the following comments to be badly
> perceived and I hope they will be seen as constructive.
>
> Browsing through the source code of Phobos, I "stumbled" upon the huge
> block that is std.datetime. Now I know that know that date/time is a
> very complex subject, and that this module has been written by Jonathan
> Davis, who is one of the smartest guys out there, so I am certainly not
> going to comment on the implementation.
>
> However, I believe the interface is way too big at the moment, and would
> highly benefit from being broken up into more focused modules. Just
> looking at the std.datetime Ddoc is a pain, let alone understanding how
> to do fairly simple tasks.
>
> For me, the module contains way too many disparate concepts to be usable
> at the moment:
> - time zones
> - calendars
> - time intervals and ranges over intervals
> - formatting and validation
> - stopwatch
> - benchmark
>
> It looks that everything time related has been crammed in this single
> module. It makes it unnecessarily hard to understand what to choose and
> how to use it. Also,>34,000 LOC makes the code nearly impossible to
> review and help/correct for people who are not the authors.
>
> I would suggest breaking this module into submodules per concept or
> activity, maybe something like:
> std.datetime.timezone
> std.datetime.calendar
> std.datetime.interval
> std.datetime.format
> and I would entirely remove everything related to stopwatch and
> benchmarking for another module.
>
> What do you think ?

Yes, please make a package of this module and split the module into several smaller modules, it IS too big.

-- 
/Jacob Carlborg

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.

-- 
/Jacob Carlborg

On Mon, 07 Nov 2011 09:20:55 -0000, Jacob Carlborg <doob@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.

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

R

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

On 2011-11-07 11:53, Regan Heath wrote:
> On Mon, 07 Nov 2011 09:20:55 -0000, Jacob Carlborg <doob@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. 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.

> 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
>
> R

C# and especially Java have only one class per file, this is not the case for D and certainly not for Phobos.

-- 
/Jacob Carlborg

On Mon, 07 Nov 2011 12:22:24 -0000, Jacob Carlborg <doob@me.com> wrote:
> On 2011-11-07 11:53, Regan Heath wrote:
>> On Mon, 07 Nov 2011 09:20:55 -0000, Jacob Carlborg <doob@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/

On 2011-11-07 14:14, Regan Heath wrote:
> 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.

That's a good point.

-- 
/Jacob Carlborg