Documentation generation

Walter Bright newshound2 at digitalmars.com
Sat Aug 7 12:53:15 PDT 2010


bearophile wrote:
> Walter has said that putting ddoc inside the compiler helps keep ddoc
> uniform, so people don't invent/use something different. In theory this is a
> nice purpose, but in practice I have seen lot of people use other
> documentation means for D, Doxygen. Walter seems to ignore how much often
> such other systems are used instead of ddoc.

It's fine if people choose to use other documentation systems. Ddoc, though, 
sets a minimum standard, and it's always there, requires no additional installs, 
is always synced to the compiler, is always on every platform D is, etc.

My experience with languages that do not have built in doc abilities is, by and 
large, only a tiny minority of programmers use a doc system. Having to research, 
download, install, read the manual, address incompatibilities, etc., takes 
effort and the reality is that by making such effort close to zero it greatly 
encourages people to use it.

The same goes for unit tests.

For another example, back in the 80's, it was commonplace for people to dis the 
C text preprocessor as "not a real macro system". Those who wanted a better one 
were advised to "just use m4". How many people using C or C++ today use m4 as 
the preprocessor? Zilch. The C preprocessor was good enough to get the job done, 
it was always there, always ready, and that was that.

(Note that I'm not defending the preprocessor, I'm just illustrating the power 
of having something built in as opposed to being a separate tool.)


More information about the Digitalmars-d mailing list