Am 22.12.2012 00:46, schrieb 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.

Thanks for the feedback. I'll continue to improve things along the way.

> 
> * 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.

I'll try to get closer to the original there. There are some differences 
because the current pages
use a lot of non-semantic formatting (<b>, <br> etc) and the result of this 
needs to be simulated
using CSS now.

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

This is actually a bug of the JSON output. Sometimes it will just output a 
simple "template" node
instead of "function" nested in a "template". In that case there is not much I 
can do,
unfortunately. But I hope that this will be addressed by the big DDOC pull 
request.

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

Right. Any preference? I would go for header + only "Name" in the table to keep 
it visually
structured (I actually could have sworn I already did that some time ago, but 
the commit is probably
lying locally on another machine).

> 
> * 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.

The DDOC spec says that the first paragraph is the short summary (BLURB), 
followed by the long
summary, which goes until the first section header. Some modules are not using 
this correctly and
have a very long paragraph at the beginning.

(See http://dlang.org/ddoc.html under "Sections")

So currently the short description is repeated on the individual page, because 
there often is
distinct content in it. That would also be an interesting documentation style 
decision, if the long
summary must be able to stand alone (which would probably be nicer).

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

Due to the naming convention (module/package names lowercase) it somehow is. 
But for the individual
pages, the distinction of class, struct, enum, function etc. is important. 
Putting "Module" in front
of the module name is consistent with the other pages in this regard. But I 
have no strong feeling
about this either.

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

Agreed. The current icon is just a place holder. Any style precedence or 
preference? (e.g. old
windows style with +/- or the new triangle thing)

> 
> * 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.

Yeah, that's the really nice aspect of it. You can actually feel the urge to 
write more detailed
documentation because of this (at least I can ;) ).

> 
> * 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.

An easy option would be http://disqus.com/ - I've seen this used quite often 
recently.

Btw., regarding sections, if, at some point, we want to visually separate 
individual sections (or
make them collapsible), a careful pass through Phobos will be necessary, 
because sections are often
introduced accidentally (e.g. a line "Example:" before a code block or 
"Copyright: ... on a single
line), resulting in an illogical structure.

> 
> * 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.
> 

A simple improvement would be to at least use a line anchor and automatically 
scroll to the right
line. Displaying only the entity would require a new JSON field for the ending 
line of an entity
(and some more work, of course).

Reply via email to