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
