On Mon, 07 Nov 2011 12:22:24 -0000, Jacob Carlborg <[email protected]> wrote:
On 2011-11-07 11:53, Regan Heath wrote:
On Mon, 07 Nov 2011 09:20:55 -0000, Jacob Carlborg <[email protected]> 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/
