Andrei's Google Talk

[Jonathan M Davis]

On Saturday 14 August 2010 13:06:04 retard wrote:
> Comparing hand-written html to ddoc is a bit unfair. I've used several
> CMS and template systems. They even have good support for D. My
> experiences tell me that
> 
> 1. ddoc has worse productivity than real document generators such as
> doxygen or good cms/markup/web template systems.
> 
> 2. these other systems also support commenting out stuff
> 
> 3. these other systems also support generating correct, conforming HTML/
> XML/TeX/PDF/MAN/whatever. With ddoc you need to use some semi-official
> templates you need to dig from the newsgroup archives. Doxygen provides
> all this by default. How is that bad for productivity?
> 
> 4. these other systems also support conditional compilation
> 
> 5-6. these other systems also support separating the style/layout from
> the structure.
> 
> 7. ditto (and it's better than what ddoc produces by default)
> 
> 8. ditto (and it's better than what ddoc produces). ddoc doesn't extract
> all components of symbol signatures in a structured way.
> 
> 9. ditto
> 
> 10. the other systems look better than ddoc
> 
> So overall the other systems are much better and I also think I could
> write something 10 times better than ddoc in 2..7 days if someone would
> give me an untainted GPL licensed frontend that didn't look so butt ugly.

It's quite possible that other documentation generators are better than ddoc, 
but to some extent, that's not the point. ddoc is supposed to be simple and 
always available with the D compiler so that there is always a doc generator 
which you can count on. By having it included with the compiler, it encourages 
people to actually write documentation and generate it. People who actually care 
about writing good documentation anyway and are looking for powerful doc 
generators can easily use more powerful doc generators such as doxygen. Whether 
ddoc exists or not has no effect on that.

So, I don't think that there's really much reason to harp on ddoc. If there are 
improvements which can be made to it without making it more complex or harder to 
use, then I'm sure that Walter is open to them (especially if they make it 
simpler and/or _easier_ to use). But it's not meant to be the end all and be all 
of doc generators. 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.

- Jonathan M Davis