Documentation generation

[Lurker]

Walter Bright Wrote:

> 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%.

That's just silly. People using 15 different good document generators is much better than one s**y one with s**y templates you need to dig from old newsgroup posts.

> 
> 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.

His idea was probably to separate the tools and still provide them both as part of the standard distribution. It would be your duty to keep both up to date.

> 
> 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.

D already has several document generators because ddoc is way too primitive. Luckily the main competition (Tango) died because of an organized FUD attack.

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

The output is still a huge joke compared to tools like doxygen and javadoc. No offense. And those are rather basic document generation tools -- better ones exist.

> 
> 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).

The integrated unit test is a joke. Spend 30 minutes with Java 6 someday and try JUnit. Or maybe few hours. The more you use, the more you learn. If you open your eyes, you might actually see how crippled your vision of unit testing is. The integrated unittest stuff brings almost zero value when doing serious software development.

> 
> 7. Contrary to what you state, making ddoc a separate utility will make it far 
> harder to maintain, not easier.

One of the main reasons why 3rd party tool support sucks is that YOU have zero ability communicating technical details to the community. We can see it in documentation. Almost none exists. People make lots of questions here and instead of answering you always focus on bikeshedding.

> 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.

That's not a surprise. If a docgen tool and a compiler frontend coming from a single vendor didn't share any code, I wouldn't call it software engineering. It would be a horrible toy project written by an amateur.