On 11/03/2012 19:04, Ary Manzana wrote:
<snip>
I don't understand why you related dynamic class' loading with a documentation
system/syntax for D.
Because that's what Javadoc relies on as a means for a program distributed in binary form
to call custom code.
OK, so there are native ways to do this, like DLLs and SOs. I don't really know whether
these are fit for the purpose. It might get a bit complicated supporting the D object
model with DMD being written in C++.
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.
OK, so writing a new documentation generator based on the DMD front end code is another
approach. Did you just write it in C++, or do the extra work so that you could write it in D?
Either way, it's good that you've written a D documentation generator that's better than
standard Ddoc, and no doubt handles D much better than Doxygen does. Have you released it
anywhere?
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?
I guess because not that much work has gone into Ddoc so far.
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).
By "formatting information" are you talking about semantic/logical markup or
presentational/physical markup?
http://webtips.dan.info/logical.html
talks about the differences between them - written from an HTML point of view but I
suppose equally applicable to Ddoc macros.
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.
To replace the current Ddoc comment format, or to give the user the choice between that
and whatever else?
Replacing the current format would be a breaking change.
Having two formats built into DMD would seem silly, aside from the question of how you
would specify which is being used in a given project. The idea of Ddoc is that it's the
standard D way of doing documentation. If a compiler has built-in documentation
generation, it should use either a format that is part of the language standard or some
established format such as Doxygen, rather than some non-portable ad-hoc format. Which is
what what you're thinking of doing would be, unless it's incorporated into the language
standard. But having two documentation comment formats in the language standard is itself
something that doesn't seem to make sense. It would be like the whole D language having
two syntaxes.
Stewart.
