Cross-references in generated ddoc

[Ary Manzana]

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. :-)