Cross-references in generated ddoc

[Jacob Carlborg]

On 2012-04-04 15:53, Ary Manzana wrote:

> 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

Thanks, much better now :)

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

For example, Phobos uses XREF to reference symbols. The template 
parameter doesn't matter since that will refer to the same function.

> 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 guess you're right.

> Thanks. I had a problem with template members. It's now fixed.
>
> http://pancake.io/1e79d0/complex.html#Complex.toString

Good.

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

Ok, I see. But why don't you create $DT_WITH_ID then :)

> 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?

I think the original idea was to be able to directly output PDF or 
similar but I don't think that turned out so well. Now Walter also says 
he is way more productive when using ddoc instead of plain HTML. That's 
why dlang.org is written using ddoc.

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

Fair enough. I think it's great what you've done with the doc generator 
but it can become even better. Like listing methods from base classes, 
listing inherited classes and implemented interfaces inherit doc 
comments and so on, just like Descent does.

-- 
/Jacob Carlborg