www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - links to nested structure

reply jdrewsen <jdrewsen nospam.com> writes:
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
Aug 23 2011
next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Aug 23 2011
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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!
Aug 23 2011
next sibling parent jdrewsen <jdrewsen nospam.com> writes:
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
Aug 23 2011
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Aug 23 2011
parent reply jdrewsen <jdrewsen nospam.com> writes:
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
Aug 24 2011
parent Adam Ruppe <destructionator gmail.com> writes:
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.
Aug 24 2011
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
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
Aug 23 2011
prev sibling parent Johannes Pfau <spam example.com> writes:
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

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 =3D <a name=3D"$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 =3D <a name=3D"$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. --=20 Johannes Pfau
Aug 24 2011