Phobos Docs Questions

Confused via Digitalmars-d digitalmars-d at puremagic.com
Sun Jan 11 13:41:13 PST 2015


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
2. Improving ddoc with some Markdown capabilities
3. Moving Phobos docs to page-per-symbol
4. Adding adding discussion to documentation pages
5. Moving Phobos docs from ddoc to ddox

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.

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.

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?
  * If ddoc isn't good enough for Phobos, why is it in the 
compiler?
  * If we want ddoc in the compiler, then why not dogfood that for 
Phobos?
  * If we don't want ddoc in the compiler, why is spend time 
improving it?

Thanks.


More information about the Digitalmars-d mailing list