Phobos Docs Questions

[Andrei Alexandrescu via Digitalmars-d]

On 1/11/15 1:41 PM, Confused wrote:
> Recently I've seen documentation work, but am confused about some
> specifics.
>
> I've seen work and/or talk being done towards...
>
> 1. Improving the text of the documentation itself

Yes please.

> 2. Improving ddoc with some Markdown capabilities

We have https://github.com/D-Programming-Language/dmd/pull/4228 about to 
make it - for now I think that's going to improve things significantly.

> 3. Moving Phobos docs to page-per-symbol

Yah, though quality is not there yet.

> 4. Adding adding discussion to documentation pages

Yah.

> 5. Moving Phobos docs from ddoc to ddox

Yah, though again we need serious work on quality.

> While I appreciate (1) and (2), I don't see the appeal of (3), and am
> strongly opposed to (4) and (5).
>
> As I see it (3) only serves to make it harder to browse the
> documentation and increases server load, but I can probably live with it
> if other people think it is a good idea. I should point out that I'm not
> aware of any other quality web-based docs for *anything* that put each
> symbol on its own page.

No worries, the extant docs are here to stay. I plan to put at the 
beginning of each module a link with text like "See single-page 
documentation".

> I also don't like the idea of (4), because it is a huge extra moderation
> requirement which I don't think this community can actually handle, and
> it will only age, causing it to be yet another source of wrong
> information about Phobos/D.

The way I see it is: to swim, we gotta get out feet wet.

> However, my main concern is with (5), which leads me to some questions:
>
>   * If ddoc is good enough for Phobos, why use another semi-compatible
> tool?

Mostly because it's there. It's possible to make ddoc generate 
file-per-entity or automatic cross-indexing. It's been on my list for 
years, but still haven't gotten to it. So why not just ddox? (It does 
build now.)

>   * If ddoc isn't good enough for Phobos, why is it in the compiler?

ddoc is a terrific and incredibly underrated tool, which can (and should 
and probably will) be taken further with simple improvements. Note that 
ddox also works on top of ddoc. Also, again, the ddoc-generated 
documentation is plenty good and will continue to be available.

>   * If we want ddoc in the compiler, then why not dogfood that for Phobos?

It is and it will continue to be there. Oh, one more thing - the website 
pages proper (language reference) use ddoc.

>   * If we don't want ddoc in the compiler, why is spend time improving it?

We do want and we should spend.


Andrei