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.
