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
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
parent reply "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
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
next sibling parent Johannes Pfau <spam example.com> writes:
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
prev sibling 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