Documentation generation

[Walter Bright]

bearophile wrote:
> Removing that HTML ddoc parsing & HTML generation from DMD allows such code
> to evolve faster and to be debugged more efficiently. Today some people are
> using

There are very good reasons why ddoc is part of dmd.

1. Being a defined part of D means it's ALWAYS there. That means there won't be 
D compilers without ddoc. That means that people can rely on it being there, and 
use it with confidence.

2. Please do not underestimate the power of something reliably being there. In 
my experience, it makes it FAR more likely that people will actually use it, and 
there's the big win. If it's a separate utility, I guarantee you that usage of 
ddoc will drop probably by 90%.

3. A separate ddoc utility means that, inevitably, dmd and ddoc will get out of 
sync with each other. People will update dmd and not ddoc, and vice versa. There 
is quite enough grief with people mixing one version of dmd with the wrong 
version of phobos and then being mystified by the results. I can't tell you how 
many times I've helped someone who INSISTED they were using the correct 
libphobos.a and there were no others on their machine, only to eventually 
sheepishly discover another old libphobos.a on their path that was being used.

4. Making it a separate utility means others will invent "improved" ddocs, with 
the resulting balkanization and non-portability of documentation comments. See 
C++ for the affect this has.

5. The documentation of Phobos took a HUGE leap forward with the integration of 
ddoc.

6. Similar advantages can be found with the integration of unittesting in D, and 
the integration of the preprocessor with C/C++ (I'm old enough to remember when 
that was a separate program).

7. Contrary to what you state, making ddoc a separate utility will make it far 
harder to maintain, not easier. Just outputting JSON files is not enough, as 
ddoc is also able to pretty-print the declarations and do color syntax 
highlighting of coding examples. If you look at the dmd source code changes, 
you'll find that ddoc tracks changes in D's grammar and syntax with rarely any 
changes at all in the ddoc code.