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
