View mode: basic / threaded / horizontal-split · Log in · Help
December 21, 2012
Re: dlang.org Library Reference
On 2012-12-21 18:05, Andrei Alexandrescu wrote:

> s/remove/integrate/
> s/ugly/awesome/

It's ugly that they are manually created. Over 300 lines of comments 
that the doc generator should be doing automatically. I would say that 
is far from awesome.

-- 
/Jacob Carlborg
December 21, 2012
Re: dlang.org Library Reference
On 2012-12-21 19:31, Sönke Ludwig wrote:

>>> What also would be nice is to have the methods inline, expandable.
>
> Would that mean the Classes/Structs/... tables as f.ex. in std.datetime?
> So there would be a small clickable thing and all members would fly out below it as direct links?
> and possibly with the short description?
> What about different kinds of members? Only methods, all grouped by type or all in one list?
>
> I'm just asking because I don't have any preferences for how such a thing should look like.

I was mostly thinking of the free functions. Instead of going to a new 
page when clicking on a function it would just expand the same content 
inline. For classes and structs we might want to keep the separate page 
since it will contain additional members. But I'm not sure.

-- 
/Jacob Carlborg
December 21, 2012
Re: dlang.org Library Reference
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
December 21, 2012
Re: dlang.org Library Reference
On 12/21/12 6:46 PM, Andrei Alexandrescu wrote:
[snip]

Forgot to emphasize what I already mentioned: alphabetic order is okay, 
but I wonder how we can integrate that with grouping per functionality 
area (the way std.algorithm does).

Andrei
December 21, 2012
Re: dlang.org Library Reference
Andrei Alexandrescu:

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

Compare a page like this:
http://dlang.org/phobos/std_array.html

With the docs of the Prelude module of Haskell:
http://www.haskell.org/ghc/docs/latest/html/libraries/base/Prelude.html

Similarly in the pages of D Phobos docs I'd like each function to 
have a link to its source, and not just have a single link to the 
whole module. This allows to find faster the source code of that 
function.

Bye,
bearophile
December 22, 2012
Re: dlang.org Library Reference
On Fri, 21 Dec 2012, Andrei Alexandrescu wrote:

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

I love community / croudsourcing.  But where it falls down in most of the 
examples I've seen is that the majority of the feedback / comments really 
belong as edits to the actual content, not additional notes.  We need to 
aim for making both happen, imho.  Allow ad-hoc extra feedback, but also 
get it cycled into the core page contents.

The current separate wiki pages that mirror the dlang site are the worse 
of both worlds in that the content exists, is hardly ever folded in, and 
isn't even visible along side the page but hidden off behind a link that I 
bet most people never even see.

Thoughts?

Later,
Brad
December 22, 2012
Re: dlang.org Library Reference
On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu 
wrote:
>
> * "Module" in the title is redundant I guess.
>

I don't think it is redundant because when you are looking at a 
page, the module as the title instantly tells you (or reminds 
you) what module you are looking at, otherwise you'll have to do 
a little bit more digging than should be necessary.

--rt
December 22, 2012
Re: dlang.org Library Reference
On Saturday, 22 December 2012 at 00:00:43 UTC, Brad Roberts wrote:
> The current separate wiki pages that mirror the dlang site are 
> the worse
> of both worlds in that the content exists, is hardly ever 
> folded in, and
> isn't even visible along side the page but hidden off behind a 
> link that I
> bet most people never even see.
>
> Thoughts?
>
> Later,
> Brad

I think the reason for the disconnection is due to the docs not 
being stored with the wiki and I don't see what can be done to 
merge the two since they are  two completely separate and 
different sources of documentation.

BTW, it turns out I didn't notice the wiki link until after 
reading your post! The link should be a button or something else 
that's much more noticeable and friendly for users to explore.

One grip do I have is that the "improve this page" system is 
rather unfriendly, and because of this I've not yet taken the 
time to research what I have to do to get to the point where I 
can contribute improvements. I suspect it turns away most people 
who otherwise would try and contribute.

In any event, what I see with the new document format is a very 
very large improvement and the sooner it is implemented (even 
with some of the minor flaws not yet fixed) the better.

--rt
December 22, 2012
Re: dlang.org Library Reference
On 12/21/12 7:16 PM, Brad Roberts wrote:
> I love community / croudsourcing.  But where it falls down in most of the
> examples I've seen is that the majority of the feedback / comments really
> belong as edits to the actual content, not additional notes.  We need to
> aim for making both happen, imho.  Allow ad-hoc extra feedback, but also
> get it cycled into the core page contents.

The way I see it, changes to the core page contents go via github. The 
community-provided notes are crowdsourced and occasionally moderated.

> The current separate wiki pages that mirror the dlang site are the worse
> of both worlds in that the content exists, is hardly ever folded in, and
> isn't even visible along side the page but hidden off behind a link that I
> bet most people never even see.
>
> Thoughts?

That's why I'm saying the wiki pages should be accessible immediately 
alongside the abstractions they document.


Andrei
December 22, 2012
Re: dlang.org Library Reference
On 12/21/12 7:29 PM, Rob T wrote:
> On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu wrote:
>>
>> * "Module" in the title is redundant I guess.
>>
>
> I don't think it is redundant because when you are looking at a page,
> the module as the title instantly tells you (or reminds you) what module
> you are looking at, otherwise you'll have to do a little bit more
> digging than should be necessary.
>
> --rt

I was referring only to the actual word.

Andrei
1 2 3 4 5 6 7 8
Top | Discussion index | About this forum | D home