Hi,

   How do I make a link to a nested class in ddoc. I tried $(LREF OuterClass.InnerClass) but that doesn't work because the anchor that is created automatically for InnerClass is just called "InnerClass".

Thanks
Jonas

On Tuesday, August 23, 2011 21:39:51 jdrewsen wrote:
> Hi,
> 
>     How do I make a link to a nested class in ddoc. I tried $(LREF
> OuterClass.InnerClass) but that doesn't work because the anchor that is
> created automatically for InnerClass is just called "InnerClass".

DDoc does not understand scoping at all. _Everything_ is at the global scope as far as it is concerned. It has no concept of a function or member variable being inside of a class or struct. It's a major flaw in ddoc, but no one has taken the time to fix it yet. So, for now, you're pretty much out of luck.

- Jonathan M Davis

Jonathan M Davis wrote:
> DDoc does not understand scoping at all.

Actually, DDoc understands scoping very well, and even outputs the data with appropriate nesting in HTML!

The problem is that the <a name=""> anchors discard that information for whatever reason.

I'm not sure if it's just another crappy macro in the std.ddoc or if it's that the full name isn't made available by ddoc, but either way, the HTML actually does show scopes properly. A post-processor can create proper anchors from just that existing structure!

On Tuesday, August 23, 2011 12:50 Adam D. Ruppe wrote:
> Jonathan M Davis wrote:
> > DDoc does not understand scoping at all.
> 
> Actually, DDoc understands scoping very well, and even outputs the data with appropriate nesting in HTML!
> 
> The problem is that the <a name=""> anchors discard that information for whatever reason.
> 
> I'm not sure if it's just another crappy macro in the std.ddoc or if it's that the full name isn't made available by ddoc, but either way, the HTML actually does show scopes properly. A post-processor can create proper anchors from just that existing structure!

You're right. Aside from the anchors, ddoc deals with the scoping properly, but as far as the anchors go, ddoc doesn't deal with the scoping property at all. I'm fairly certain that the anchors are generated by ddoc, not std.ddoc (it generates the links at the top of the page using the anchors, but as far as I can tell, the anchors exist before std.ddoc does it's thing). So, unless ddoc itself is fixed, the only way to get proper anchors is to process the files after ddoc has done its thing, which really isn't acceptable. It needs to be fixed. The problem is that we need someone who knows enough about ddoc to be able to fix it to take the time to fix it - either that or someone needs to learn. I've been tempted to dig in and do it so that std.datetime's links can be made sane, but the task seems daunting enough that I haven't really looked into it yet. I may have to though if no one else steps up, since std.datetime's links really need to be improved.

- Jonathan M Davis

Den 23-08-2011 22:26, Jonathan M Davis skrev:
> On Tuesday, August 23, 2011 12:50 Adam D. Ruppe wrote:
>> Jonathan M Davis wrote:
>>> DDoc does not understand scoping at all.
>>
>> Actually, DDoc understands scoping very well, and even outputs
>> the data with appropriate nesting in HTML!
>>
>> The problem is that the<a name="">  anchors discard that
>> information for whatever reason.
>>
>> I'm not sure if it's just another crappy macro in the std.ddoc or
>> if it's that the full name isn't made available by ddoc, but either
>> way, the HTML actually does show scopes properly. A post-processor
>> can create proper anchors from just that existing structure!
>
> You're right. Aside from the anchors, ddoc deals with the scoping properly,
> but as far as the anchors go, ddoc doesn't deal with the scoping property at
> all. I'm fairly certain that the anchors are generated by ddoc, not std.ddoc
> (it generates the links at the top of the page using the anchors, but as far
> as I can tell, the anchors exist before std.ddoc does it's thing). So, unless
> ddoc itself is fixed, the only way to get proper anchors is to process the
> files after ddoc has done its thing, which really isn't acceptable. It needs
> to be fixed. The problem is that we need someone who knows enough about ddoc
> to be able to fix it to take the time to fix it - either that or someone needs
> to learn. I've been tempted to dig in and do it so that std.datetime's links
> can be made sane, but the task seems daunting enough that I haven't really
> looked into it yet. I may have to though if no one else steps up, since
> std.datetime's links really need to be improved.
>
> - Jonathan M Davis

For now I've worked around it by introducing a new DDOC_ANCHOR in std.ddoc that I hope will get accepted. This makes it possible for me to reference my inner struct/classes.

/Jonas

Jonathan M Davis wrote:
> I'm fairly certain that the anchors are generated by ddoc, not std.ddoc

Well, it's a bit of both.

DDOC_PSYMBOL = <a name="$0"></a>$(U $0)

Looking at doc.c, DDOC_PSYMBOL is used in the toDocBuffer() methods.
The paramater to it is always this.toChars().

I'm not sure how to do it best. It could probably just do a
parent.toChars() ~ "." ~ toChars() (conceptually) but then it
would output stuff like:

struct <u>Outer.Inner</u>

which still isn't ideal.

But, I think this might be ideal:

("$(DDOC_PSYMBOL %s %s)", toChars(), parent.toChars() ~ [...]);


Then, the macro in std.ddoc can be changed to be like this:

DDOC_PSYMBOL = <a name="$2"></a>$(U $1)


So you keep the simple info and the more detailed name.


I've gotta look at the dmd source to see what's there for the parent member, but I'm sure there's something.


Maybe I'll do up a pull request this weekend if nothing else comes up on my schedule.

Adam D. Ruppe wrote:
>Jonathan M Davis wrote:
>> I'm fairly certain that the anchors are generated by ddoc, not std.ddoc
>
>Well, it's a bit of both.
>
>DDOC_PSYMBOL = <a name="$0"></a>$(U $0)
>
>Looking at doc.c, DDOC_PSYMBOL is used in the toDocBuffer() methods.
>The paramater to it is always this.toChars().
>
>I'm not sure how to do it best. It could probably just do a
>parent.toChars() ~ "." ~ toChars() (conceptually) but then it
>would output stuff like:
>
>struct <u>Outer.Inner</u>
>
>which still isn't ideal.
>
>But, I think this might be ideal:
>
>("$(DDOC_PSYMBOL %s %s)", toChars(), parent.toChars() ~ [...]);
>
>
>Then, the macro in std.ddoc can be changed to be like this:
>
>DDOC_PSYMBOL = <a name="$2"></a>$(U $1)
>
>
>So you keep the simple info and the more detailed name.
>
>
>I've gotta look at the dmd source to see what's there for the parent member, but I'm sure there's something.
>
>
>Maybe I'll do up a pull request this weekend if nothing else comes up on my schedule.

Maybe toPrettyChars in dsymbol.c is useful here. AFAIK it's supposed to output the full name of a symbol.

-- 
Johannes Pfau

Den 23-08-2011 22:38, Adam D. Ruppe skrev:
> Jonathan M Davis wrote:
>> I'm fairly certain that the anchors are generated by ddoc, not std.ddoc
>
> Well, it's a bit of both.
>
> DDOC_PSYMBOL =<a name="$0"></a>$(U $0)
>
> Looking at doc.c, DDOC_PSYMBOL is used in the toDocBuffer() methods.
> The paramater to it is always this.toChars().
>
> I'm not sure how to do it best. It could probably just do a
> parent.toChars() ~ "." ~ toChars() (conceptually) but then it
> would output stuff like:
>
> struct<u>Outer.Inner</u>
>
> which still isn't ideal.
>
> But, I think this might be ideal:
>
> ("$(DDOC_PSYMBOL %s %s)", toChars(), parent.toChars() ~ [...]);
>
>
> Then, the macro in std.ddoc can be changed to be like this:
>
> DDOC_PSYMBOL =<a name="$2"></a>$(U $1)
>
>
> So you keep the simple info and the more detailed name.
>
>
> I've gotta look at the dmd source to see what's there for the
> parent member, but I'm sure there's something.
>
>
> Maybe I'll do up a pull request this weekend if nothing else
> comes up on my schedule.

Would this also handle double nested classes etc.?

/Jonas

Yeah, it should work with any level of nesting.

If toPrettyChars() doesn't work out, my parent
plan is actually more like:

auto item = this.parent;
while(item) {
 str ~= "." ~ item.toChars();
 item = this.parent;
}

so it'd go any level needed.