Cross-references in generated ddoc
Ary Manzana
ary at esperanto.org.ar
Wed Apr 4 06:53:37 PDT 2012
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. :-)
More information about the Digitalmars-d
mailing list