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.
