View mode: basic / threaded / horizontal-split · Log in · Help
March 28, 2012
Re: std.containers - WAT
On Wed, Mar 28, 2012 at 02:46:19PM +1300, James Miller wrote:
> In helping someone in D.learn, I ended up looking through the
> documentation and code for std.containers.
> 
> There is a lot wrong with whats going on there right now.
[...]

IIRC, Andrei is planning to redesign (or do some major cleanup of)
std.containers at some point.

OTOH, I have to agree that a lot of Phobos documentation can do with
some improvement. I've been trying to do just this whenever I get some
free time. Currently I have a pull request for improving std.range's
docs -- the current docs are very unfriendly to a newbie; you can only
make sense of it if you already know what ranges are.

Anyway, it would be great if more people can help with the docs. Just
create an account on github and fork D-Programming-Language/phobos and
D-Programming-Language/d-programming-language.org, run `git clone` on
both repositories in the same directory, create a new branch, and edit
away.  When you're ready to test, run a `make html` in the phobos
directory. This will generate a copy of the docs on your local machine
under ../web/phobos-prerelease/, which you can point your browser at.
When you're happy with your changes, go to github and initiate a pull
request on phobos from your working branch.


T

-- 
Recently, our IT department hired a bug-fix engineer. He used to work for Volkswagen.
March 28, 2012
Re: std.containers - WAT
On 28 March 2012 17:00, H. S. Teoh <hsteoh@quickfur.ath.cx> wrote:
> Anyway, it would be great if more people can help with the docs. Just
> create an account on github and fork D-Programming-Language/phobos and
> D-Programming-Language/d-programming-language.org, run `git clone` on
> both repositories in the same directory, create a new branch, and edit
> away.  When you're ready to test, run a `make html` in the phobos
> directory. This will generate a copy of the docs on your local machine
> under ../web/phobos-prerelease/, which you can point your browser at.
> When you're happy with your changes, go to github and initiate a pull
> request on phobos from your working branch.

Lol, I am doing my best, I currently have a pull request for a typo
(not exactly a massive change, but every bit helps) and I will
probably contribute more when I have more experience with what is
there. I would say that I could improve the documentation for
std.algoritm, since I'm using it a lot right now, but its actually
pretty good, so that's kinda out of the question.

Knowing more about ranges would be very useful for people, since while
people have the understand that a range is a sequence of values
between two values, its not that obvious how that affects the
programming side of it. While Andrei's article is good, the audience
is clearly not people that just want to know "what is a Range, and how
do I use it".

I think one more thing that needs some changing is the usability of
the documentation, right now you get a dense list at the top, in
mostly-alphabetical order (I think it puts caps first, then lower
case) and then you get a massive list of classes and functions that
are difficult to navigate.

--
James Miller
March 28, 2012
Re: std.containers - WAT
On 28-03-2012 06:13, James Miller wrote:
> On 28 March 2012 17:00, H. S. Teoh<hsteoh@quickfur.ath.cx>  wrote:
>> Anyway, it would be great if more people can help with the docs. Just
>> create an account on github and fork D-Programming-Language/phobos and
>> D-Programming-Language/d-programming-language.org, run `git clone` on
>> both repositories in the same directory, create a new branch, and edit
>> away.  When you're ready to test, run a `make html` in the phobos
>> directory. This will generate a copy of the docs on your local machine
>> under ../web/phobos-prerelease/, which you can point your browser at.
>> When you're happy with your changes, go to github and initiate a pull
>> request on phobos from your working branch.
>
> Lol, I am doing my best, I currently have a pull request for a typo
> (not exactly a massive change, but every bit helps) and I will
> probably contribute more when I have more experience with what is
> there. I would say that I could improve the documentation for
> std.algoritm, since I'm using it a lot right now, but its actually
> pretty good, so that's kinda out of the question.
>
> Knowing more about ranges would be very useful for people, since while
> people have the understand that a range is a sequence of values
> between two values, its not that obvious how that affects the
> programming side of it. While Andrei's article is good, the audience
> is clearly not people that just want to know "what is a Range, and how
> do I use it".
>
> I think one more thing that needs some changing is the usability of
> the documentation, right now you get a dense list at the top, in
> mostly-alphabetical order (I think it puts caps first, then lower
> case) and then you get a massive list of classes and functions that
> are difficult to navigate.

I think basically everyone dislikes this.

>
> --
> James Miller

-- 
- Alex
March 28, 2012
Re: std.containers - WAT
On Wed, Mar 28, 2012 at 06:58:45AM +0200, Alex Rønne Petersen wrote:
> On 28-03-2012 06:13, James Miller wrote:
[...]
> >I think one more thing that needs some changing is the usability of
> >the documentation, right now you get a dense list at the top, in
> >mostly-alphabetical order (I think it puts caps first, then lower
> >case) and then you get a massive list of classes and functions that
> >are difficult to navigate.
> 
> I think basically everyone dislikes this.
[...]

The docs for classes and functions really need to be properly
categorized according to utility, and not just presented in the order in
the code or some arbitrary ordering (like alphabetical). Alphabetical is
OK if you already know what you're looking for, but is horrible for
newbies who have no idea where to even start. (And arguably even if you
know what you want, alphabetical is only useful if you already know the
exact name... otherwise you'd still want to look it up by category
instead of name.)


T

-- 
"How are you doing?" "Doing what?"
March 28, 2012
Re: std.containers - WAT
On Tuesday, March 27, 2012 22:20:56 H. S. Teoh wrote:
> On Wed, Mar 28, 2012 at 06:58:45AM +0200, Alex Rønne Petersen wrote:
> > On 28-03-2012 06:13, James Miller wrote:
> [...]
> 
> > >I think one more thing that needs some changing is the usability of
> > >the documentation, right now you get a dense list at the top, in
> > >mostly-alphabetical order (I think it puts caps first, then lower
> > >case) and then you get a massive list of classes and functions that
> > >are difficult to navigate.
> > 
> > I think basically everyone dislikes this.
> 
> [...]
> 
> The docs for classes and functions really need to be properly
> categorized according to utility, and not just presented in the order in
> the code or some arbitrary ordering (like alphabetical). Alphabetical is
> OK if you already know what you're looking for, but is horrible for
> newbies who have no idea where to even start. (And arguably even if you
> know what you want, alphabetical is only useful if you already know the
> exact name... otherwise you'd still want to look it up by category
> instead of name.)

Alphabetical isn't all that big a deal if the docs would just maintain the 
hierarchy (e.g. putting the functions of a class with a class rather than 
lumping everything in the list at the top). But unfortunately, ddoc doesn't 
really support that right now. Some modules do have additional stuff at the top 
for organizing their stuff beyond lumping it together (e.g. std.alorithm and 
std.container), but ddoc itself needs some improvements with regards to 
anchors and the like for the links at the top to really be organized like they 
should be.

- Jonathan M Davis
March 28, 2012
Re: std.containers - WAT
On Tue, Mar 27, 2012 at 11:59 PM, Jonathan M Davis <jmdavisProg@gmx.com>wrote:

> On Tuesday, March 27, 2012 22:20:56 H. S. Teoh wrote:
> > On Wed, Mar 28, 2012 at 06:58:45AM +0200, Alex Rønne Petersen wrote:
> > > On 28-03-2012 06:13, James Miller wrote:
> > [...]
> >
> > > >I think one more thing that needs some changing is the usability of
> > > >the documentation, right now you get a dense list at the top, in
> > > >mostly-alphabetical order (I think it puts caps first, then lower
> > > >case) and then you get a massive list of classes and functions that
> > > >are difficult to navigate.
> > >
> > > I think basically everyone dislikes this.
> >
> > [...]
> >
> > The docs for classes and functions really need to be properly
> > categorized according to utility, and not just presented in the order in
> > the code or some arbitrary ordering (like alphabetical). Alphabetical is
> > OK if you already know what you're looking for, but is horrible for
> > newbies who have no idea where to even start. (And arguably even if you
> > know what you want, alphabetical is only useful if you already know the
> > exact name... otherwise you'd still want to look it up by category
> > instead of name.)
>
> Alphabetical isn't all that big a deal if the docs would just maintain the
> hierarchy (e.g. putting the functions of a class with a class rather than
> lumping everything in the list at the top). But unfortunately, ddoc doesn't
> really support that right now. Some modules do have additional stuff at
> the top
> for organizing their stuff beyond lumping it together (e.g. std.alorithm
> and
> std.container), but ddoc itself needs some improvements with regards to
> anchors and the like for the links at the top to really be organized like
> they
> should be.
>
> - Jonathan M Davis
>

Adam has a pull request addressing this issue <
https://github.com/D-Programming-Language/dmd/pull/770>.  It basically
makes anchors the full hierarchy of the symbol but without the containing
module as that would be redundant and break almost all existing links.

Regards,
Brad Anderson
March 28, 2012
Re: std.containers - WAT
On Tue, Mar 27, 2012 at 10:00 PM, H. S. Teoh <hsteoh@quickfur.ath.cx> wrote:

> On Wed, Mar 28, 2012 at 02:46:19PM +1300, James Miller wrote:
> > In helping someone in D.learn, I ended up looking through the
> > documentation and code for std.containers.
> >
> > There is a lot wrong with whats going on there right now.
> [...]
>
> [snip]

>
> Anyway, it would be great if more people can help with the docs. Just
> create an account on github and fork D-Programming-Language/phobos and
> D-Programming-Language/d-programming-language.org, run `git clone` on
> both repositories in the same directory, create a new branch, and edit
> away.  When you're ready to test, run a `make html` in the phobos
> directory. This will generate a copy of the docs on your local machine
> under ../web/phobos-prerelease/, which you can point your browser at.
> When you're happy with your changes, go to github and initiate a pull
> request on phobos from your working branch.
>
>
>
See also the "Improve this page" button I added that lets you make changes
online.  Good for typos and other smaller changes. It won't show up on
Phobos' documentation pages until new docs are uploaded but it's available
on the rest of the site already.

Regards,
Brad Anderson
March 28, 2012
Re: std.containers - WAT
On 3/27/12 10:58 PM, Alex Rønne Petersen wrote:
>> I think one more thing that needs some changing is the usability of
>> the documentation, right now you get a dense list at the top, in
>> mostly-alphabetical order (I think it puts caps first, then lower
>> case) and then you get a massive list of classes and functions that
>> are difficult to navigate.
>
> I think basically everyone dislikes this.

I agree, and I think std.algorithm offers a good alternative without 
requiring changes to ddoc. This is a good place where the community 
might greatly help - it's work that's neither too difficult nor too 
boring, and has huge impact.

Andrei
March 29, 2012
Re: std.containers - WAT
On Wednesday, March 28, 2012 08:37:30 Andrei Alexandrescu wrote:
> On 3/27/12 10:58 PM, Alex Rønne Petersen wrote:
> >> I think one more thing that needs some changing is the usability of
> >> the documentation, right now you get a dense list at the top, in
> >> mostly-alphabetical order (I think it puts caps first, then lower
> >> case) and then you get a massive list of classes and functions that
> >> are difficult to navigate.
> > 
> > I think basically everyone dislikes this.
> 
> I agree, and I think std.algorithm offers a good alternative without
> requiring changes to ddoc. This is a good place where the community
> might greatly help - it's work that's neither too difficult nor too
> boring, and has huge impact.

What std.algorithm works great and should be emulated in other modules, but 
without the anchor situation being fixed, it won't completely work for any 
modules which include enums, structs, or classes.

- Jonathan M Davis
March 29, 2012
Re: std.containers - WAT
On Wed, 28 Mar 2012 10:37:30 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail@erdani.org> wrote:

> On 3/27/12 10:58 PM, Alex Rønne Petersen wrote:
>>> I think one more thing that needs some changing is the usability of
>>> the documentation, right now you get a dense list at the top, in
>>> mostly-alphabetical order (I think it puts caps first, then lower
>>> case) and then you get a massive list of classes and functions that
>>> are difficult to navigate.
>>
>> I think basically everyone dislikes this.
>
> I agree, and I think std.algorithm offers a good alternative without  
> requiring changes to ddoc. This is a good place where the community  
> might greatly help - it's work that's neither too difficult nor too  
> boring, and has huge impact.

This is precisely the wrong way to fix this.  DDoc needs to be fixed in  
the compiler.  It's one of the lowest hanging fruits I think we have (a  
great concept (using compiler knowledge of code structure to generate  
documentaiton) that is poorly implemented).

-Steve
« First   ‹ Prev
1 2
Top | Discussion index | About this forum | D home