Thread overview | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
August 23, 2011 links to nested structure | ||||
---|---|---|---|---|
| ||||
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 |
August 23, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to jdrewsen | 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
|
August 23, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to 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!
|
August 23, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to Adam D. Ruppe | 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
|
August 23, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to 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
|
August 23, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jonathan M Davis | 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.
|
August 24, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to Adam D. Ruppe Attachments: | 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 |
August 24, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to Adam D. Ruppe | 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
|
August 24, 2011 Re: links to nested structure | ||||
---|---|---|---|---|
| ||||
Posted in reply to jdrewsen | 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. |
Copyright © 1999-2021 by the D Language Foundation