Andrei's Google Talk

[retard]

Sat, 14 Aug 2010 21:32:18 -0400, bearophile wrote:

> Yao G. Wrote:
> 
>> You are just becoming a parody of yourself.
> 
> Everyone deserves respect when expresses opinions honestly and in an
> civil way, even when the ideas are wrong.

I just made some arguments against using ddoc since in my opinion it 
provides lower productivity than the competing tools. There are perfectly 
valid reasons to not use it. These are my opinions:

 - the markup/macro syntax is NIH new. It might be simpler for Walter to 
improve on, but a user i) has to learn yet another new syntax (it's quite 
likely that a developer already knows html/xml or javadoc/doxygen style 
or something like markdown) and ii) the user has to adapt to changes 
because the functionality is very primitive and users expect more 
features as the user base grows. This is a real issue if the project 
grows beyond say 5000 LOC. The managers/users of the documented project 
might expect features such as a TOC or inter-module hyperlinks.

 - the existing ddoc documents encourage writing in "html 3.2 optimized" 
way. Other document generators try to provide a generic interface with 
documentation syntax that improves the readability of the source code. As 
a result, doxygen generates all kinds of documentation output, but ddoc 
is mostly used to produce html pages. The candydoc system with its 
terrible javascript hangs many older workstations. The same functionality 
is better achieved with a more complete document generator.

 - the simple utility looks intriguing at first, however it doesn't scale 
much up. You might wish for new features/bugfixes, but the tool has very 
low priority. You can check the commit history - nothing revolutionary 
happens usually. Also, contributing new code to the toolchain requires an 
order of magnitude more effort than learning some other document 
generator. That probably explains why ddoc development is so dead.


Someone might ask, why I don't contribute or use ddoc. I have my custom 
made filters for .d files and I use doxygen. Works just fine. On web 
pages I use a template engine with syntax highlighting support. These 
system also support D just fine nowadays. This way I've maximized my 
productivity. I can use the same documentation tool for C/C++/Java/C#/D 
projects. No need to learn new syntax.

> It's meant to be a basic, simple tool that you can count on being
> there. If you want fancier, more powerful doc generation, you're free
> to use 3rd party doc generators like doxygen.

The default toolchain creates a certain kind of ecosystem. Ddoc 
encourages amateurish hobbyist project look and feel. It can't even 
compete with javadoc or rdoc feature-wise. Comparing with C or C++ here 
is moot, because those languages were invented more or less before these 
kind of document generators even existed.

Usually the larger projects count on tools being there. But it sounds 
weird to encourage the use of primitive ddoc in those projects.