d-programming-language.com

[Adam D. Ruppe]

Jonathan M Davis Wrote:
>  In fact, as much of the documentation-
> generation as possible should be in ddoc IMHO. That way, anyone can get 
> reasonable documentation for their own projects.

I agree to an extent, but at the same time, I like keeping ddoc itself fairly
simple.

Correct anchors from ddoc are a no-brainer, it definitely should be doing that.

I'd also like for it to mark off any D names it sees, so we can link them right into
a search engine or something to do automatic cross referencing. (I want to add
this to my program too, but regardless, the compiler would do a much better job
at it than a regular expression or whatever I can do with the text.)

I'm still meaning to revamp the compiler's default set of macros too, when I
get around to it.


But, I'm mixed on things like tables of contents. On one hand, it's definitely
a useful thing to have, but on the other, how much can ddoc do without
getting a lot more complicated?

I'd hate to add a bunch of special cases in there, or worse yet, a whole bloody
scripting language, to cover everyone's use-case. If we do tables, what's next?
Though a nice content listing probably *is* worth it...

Keeping ddoc simple and running the generated document through an additional
program gives you all the flexibility of D - or whatever - without adding to the
compiler.

If you take a look at my program: http://arsdnet.net/d-web-site/improveddoc.d
you can see that it isn't terribly complex, but part of that is that it uses my
html dom library and std.algorithm to help out; of we replicated that inside
the compiler it might be a lot messier.