On 4/4/12 8:05 PM, Jacob Carlborg wrote:
On 2012-04-04 13:38, Ary Manzana wrote:
Ah, no. That's because I ran it against object.di, which doesn't have
ddoc comments at all. I don't generate cross-references to undocumented
symbols.
I uploaded a new version which I ran against an object.di which has
empty ddocs for everything. Now you can see there are some
cross-references. (if you find some is missing, please tell me).
Cool, but what I actually was referring to was template types, i.e. the
first declaration in http://pancake.io/1e79d0/array.html:
ForeachType!(Range)[] array(Range)(Range r);
"ForeachType" is not a link.
You are right!
I was missing doing cross-reference for template instances. Now I did
it, but I was actually forgetting to do cross-references for template
instances inside templates. :-P
So now I did it. Take a look, much better! :-)
http://pancake.io/1e79d0/array.html#array
Why are you not using the mangled name when creating anchors?
I don't think there's need for the mangled name. It's also more natural
to give a link like foo.html?Some.Class than a mangled name.
Sure but then it won't be possible to reference different overloaded
functions? If you're not creating your own human readable form of
mangling, i.e.
foo.html#Foo.bar(int)
foo.html#Foo.bar(char)
I think it's more important that the doc generator behaves correctly
than outputting pretty URL's.
But you can't reference a function in the generated ddoc. You could do
it manually, but then you'd have to figure out the mangling or something
like that. Also, when guessing what an identifier resolves to, I can't
possibly know which template parameters to use.
Also, all overloads will have more or less the same documentation and
they will be one next to the other. I don't think that's an issue for a
documentation system.
I found a case where the fully qualified name is not used:
http://pancake.io/1e79d0/complex.html#toString
The name is just "toString" instead of "Complex.toString".
Thanks. I had a problem with template members. It's now fixed.
http://pancake.io/1e79d0/complex.html#Complex.toString
BTW, why are adding an empty "a" tag for the anchor? Just add an "id" on
the actual tag you want to refer to.
I wanted to do that. But I have to deal with ddoc macros. Every
declaration is put inside a <dt> tag. That is issued with a $(DT ...)
macro. So I'd have to create another macro, say $DT_WITH_ID or something
like that that outputs the id.
I can't simply output an id attribute because I'm not generating html:
I'm generating ddoc.
I mean, what other formats was Walter thinking of? PDF? Just use an HTML
to PDF converter. Ummm... plain text? Microsoft Doc? I don't know. Why
can't we just generate html and that's it?
The cross-referencing worked better in Descent, why are you doing it
differently?
Well, Descent kept a lot of information to be as precise as possible.
DMD is not my code so I tried to modify it as least as possible, without
adding too much overhead to the code or memory. I just added a member to
the TypeIdentifier struct. I would need to change a lot more to make it
work as Descent worked... but I think what I did now with DMD is good
enough. :-)
