On 03/11/2012 12:46 PM, Stewart Gordon wrote:
On 11/03/2012 02:26, Kevin Cox wrote:
<snip>
I hate to say it but I think the ddoc system was way overthought. It
would be better to
use a markup language such as Creole that is meant to look nice and
you can convert that
into anything you want. You could leave the default html but provide
an api for accessing
a parsed tree.
I think this is more or less how Java doclets work. It works because
Java's bytecode and dynamic class loading provide a means to call an
arbitrary method of an arbitrary compiled class that need not be part of
the same app.
But how are we going to do this with D? It seems we would need to either:
(a) compile the doclet on the fly and pass the parse tree into it
(b) have in said API a parse tree constructor that translates it from a
textual representation received through stdin.
Stewart.
I don't understand why you related dynamic class' loading with a
documentation system/syntax for D.
Some hours ago you closed a very old enhancement report I submited:
http://d.puremagic.com/issues/show_bug.cgi?id=3161
(in fact I had totally forgotten I implemented that :-P, so thanks for
reminding it to me... thought I didn't like that you closed it as invalid)
Now, I implemented it purely based on dmd's code. I didn't add anything
else to get that done. And D is not dynamic or doesn't have dynamic
class loading.
So... can you explain a bit more?
And does somebody know why, being dmd able to compile files, which
requires having exact type information for every
method/template,whatever, generates such a poor documentation?
Another question: ddoc is used (or was used) to generate d's main site.
Wut?? So it's much more than just documenting D classes. I think this is
wrong. That's when you end up having macros and all of that, because
when generating a page you want to reuse things. But when documentation
a library, hmmm... I never needed such thing. And even though I do care
about the format of the documentation (how it looks), I definitely don't
put formatting information inside a method's documentation (except for
code snippets and lists).
Some simple like markdown or rdoc (well, the idea, not rdoc itself for D
:-P) should be more than enough.
If there's interesent, I can hack dmd into producing such documentation,
and send a pull request.
