On 03/11/2012 05:33 PM, Stewart Gordon wrote:
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.
What do you mean by "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++.
Sorry, I still don't understand you :-(
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?
I wrote it in Java, because back then I had dmd ported to Java and I
found it easy to do it that way (I'm not very efficient/fast programming
in C++).
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?
I posted it back then, it's in Descent's source code. There wasn't much
interest, though. And instead of working on a decent documentation
system you end up with documentation like this one:
https://github.com/D-Programming-Language/phobos/blob/master/std/algorithm.d#L4
Nice, a javascript tag inside of the docs. And then an excerpt:
$(BOOKTABLE ,
$(TR $(TH Category) $(TH Functions)
)
$(TR $(TDNW Searching) $(TD $(MYREF balancedParens) $(MYREF
???
Ok, a table can't be done easily in markdown or rdoc either, but a list
would have maybe been enough. Or just list the functions in alphabetical
order, top down (because it's hard to do a binary search with the eyes
from left to right, since it takes some time to spot the first letter of
every word). Like finding join here:
http://dlang.org/phobos/std_array.html
instead of here:
http://pastebin.com/ib4dJt48
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.
Documentation is the primary interface to the users of a library,
including the standard library. I believe it deserves a lot more
attention than that.
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.
Interesting reading.
I talk about semantic/logical markup. But I'd like to use one which,
when I read it, doesn't hurt my eyes (like std.algorithm docs).
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?
Replace it. Macros to document code? I think that's a bit too much...
Write a list in DDoc:
$(UL
$(LI Karatsuba multiplication)
$(LI Squaring is optimized independently of multiplication)
$(LI Divide-and-conquer division)
$(LI Binary exponentiation)
)
Write a list in rdoc or markdown:
* Karatsuba multiplication
* Squaring is optimized independently of multiplication
* Divide-and-conquer division
* Binary exponentiation
Or links. With DDoc:
$(WEB sgi.com/tech/stl/, Alexander Stepanov's Standard Template Library)
With markdown
[Alexander Stepanov's Standard Template Library](sgi.com/tech/stl/)
(well, I admit there's not much difference in this last example.
Still... it's shorter and cleaner :-P)
Replacing the current format would be a breaking change.
Only for docs that heavily use macros. I hope there's not many!
And you can always make a tool to convert ddoc to the new format (I
believe with ddoc macros?)
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.
Just leave one syntax.
