Documentation generation

[Andrei Alexandrescu]

On 08/07/2010 02:53 PM, Walter Bright wrote:
> 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.)

Boost's preprocessor library is a powerful exhibit in favor of your 
argument. I think I wouldn't be mistaken to say that everything it does 
can be done much easier and much better, plus with m4 you can do a lot 
other things of interest. But the Boost preprocessor library wins 
because "it's there".


Andrei