Can we get a forum section devoted to documentation?

[H. S. Teoh]

On Fri, Aug 16, 2013 at 04:12:11PM -0400, Jonathan M Davis wrote:
> On Friday, August 16, 2013 21:57:01 Andre Artus wrote:
> > It is disheartening to think that the people with potential for
> > the most valuable contributions or insight will be avoiding
> > discussions regarding the documentation. But I fear you are
> > correct.
> 
> There's a difference between avoiding discussions and searching after
> them. If a discussion occurs in a list that they're already subscribed
> to, they're a lot more likely to read it and contribute to it than
> they are to go and subscribe to yet another list.
[...]

Good point.

Though I have to say, actually reading Phobos code to figure out what it
does is actually much less scary than it sounds. It's orders of
magnitude better than, say, reading the source code of Glibc. Thanks to
D's superior syntax and other readability features, Phobos code actually
reads like "normal" application code for the most part. It's not that
hard to understand at all. I can't say the same for things like Glibc
(or ncurses -- I tried reading that once and my eyes bled).

And when that fails (there are some places where it isn't obvious what
the code is doing), there's always the copy-paste-modify method: copy
Phobos code into a temporary file, wrap a main() around it, and run it
yourself to see what it does. Again thanks to D's readability and
modularity features, for the most part this will actually work
painlessly. In fact, you can even copy, say, std.algorithm.find into
/tmp/test.d, then import std.algorithm at the top so that any
subfunctions or subtemplates that it calls will automatically resolve
back to the Phobos code, but when main() calls find(), your copy of
find() gets used instead because the local module gets higher preference
when resolving overloads. Then you can modify your copy of find() to
your heart's content and observe what it does, etc.. Man I love D...

Try doing that with glibc or ncurses code, for example, and ... well,
let's just say you *don't* want to try this at home, you may be scarred
for life. :-P


T

-- 
Let X be the set not defined by this sentence...