dlang.org Library Reference

[Andrei Alexandrescu]

On 12/21/12 7:24 AM, Sönke Ludwig wrote:
> Example generated site is here:
>
> http://vibed.org/temp/d-programming-language.org/phobos/index.html
>
>
> Is any further work on this desired?

Thanks for this work! Let me provide a little feedback. I'm looking 
mainly at std.array and std.algorithm.

* There's lots of wasted real estate at the top of the page: the source, 
license, and authors sections are way spaced. They should compactly fill 
the top of the page.

* Differentiating "Functions" and "Templates" is unnecessary and 
tenuous. Generic functions are functions. Everything should go in one place.

* The paragraph heading "Functions:" followed immediately by "Function 
name" is redundant.

* The individual pages repeat the text on the page. We should have a way 
to differentiate the blurb from the full description. For example:

// inside array.d
/**
$(BLURB Replace occurrences of from with to in subject.) Returns a new 
array without changing the contents of subject, or the original array if 
no match is found.
*/
E[] replace((E,R1,R2) if (isDynamicArray!(E[]) && isForwardRange!(R1) && 
isForwardRange!(R2) && (hasLength!(R2) || isSomeString!(R2))))(   E[] 
subject,   R1 from,   R2 to ) { ... }

The blurb would be present in the short doc, and the blurb followed by 
the rest of the text and the signature would appear in the full page.

* "Module" in the title is redundant I guess.

* The styling on the "+" signs in the left column should be different 
when the tree branch is open or closed.

* I yearned for a long time for a per-symbol page, and I'd be really 
happy to migrate toward that. One important consequence here is that we 
can improve each function's (struct's, class' etc) documentation without 
bloating the general documentation, which remains terse. In that vein, 
I'm looking at the PHP docs (which have opted for a similar structure) 
and that are of excellent quality. See e.g. 
http://us1.php.net/manual/en/function.fopen.php that inspires a few 
bullets below.

* There's a "Changelog" section which we can add to help with any 
backward compatibility issue.

* "See also" is awesome.

* But by very, very far the community-contributed stuff is just perfect. 
I really really really hope we can get something like that integrated. 
There are many ways to approach this:

- By integrating a wiki page via e.g. an IFRAME.
- By integrating with github
- Through a separate custom layer (a la forum.dlang.org)
- Whatever it is, we'd need some crowdsourcing (voting system etc) such 
that good community notes go up and bad notes go down or get ultimately 
deleted.

* Would be awesome to have the implementation at entity level in an 
expandable IFRAME instead of linking to the entire github implementation 
of the file.


Thanks,

Andrei