www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - ddoc crossreferences

reply Morusaka <morusaka inwind.it> writes:
Hi,

is there a way to include cross references in my documentation.
For example, i'd like to do something like:

/**
 * foo bla bla bla
 * See_Also:
 * bar <i'd like a link here!!>
 */
void foo() {...}

/**
 * bar bla bla
 * See_Also:
 * foo <i'd like a link here!!>
 */
void bar() {...}

and i'd like elements in See_Also section to be link to other points in the
same file documentation.

How can i do this? (maybe with the LINK macro, but i can't figure out how)

Thank you,

Luca.
Nov 29 2008
parent reply Morusaka <morusaka inwind.it> writes:
Ok, with the help of grep i've found a lot of examples in Tango sources, for
instance in: tango/text/locale/Core.d

$(LINK2 #whereToGo, linkName)
...
...
...
$(ANCHOR whereToGo)
...
...
...

Now I wonder if this is the right way to do this... i mean if the documentation
has to be processed in order to produce a pdf version of it, does this html
stuff will work?

Thank you,

Luca.


Morusaka Wrote:


 Hi,
 
 is there a way to include cross references in my documentation.
 For example, i'd like to do something like:
 
 /**
  * foo bla bla bla
  * See_Also:
  * bar <i'd like a link here!!>
  */
 void foo() {...}
 
 /**
  * bar bla bla
  * See_Also:
  * foo <i'd like a link here!!>
  */
 void bar() {...}
 
 and i'd like elements in See_Also section to be link to other points in the
same file documentation.
 
 How can i do this? (maybe with the LINK macro, but i can't figure out how)
 
 Thank you,
 
 Luca.
Nov 29 2008
parent reply Morusaka <morusaka inwind.it> writes:
Morusaka Wrote:


 Ok, with the help of grep i've found a lot of examples in Tango sources, for
instance in: tango/text/locale/Core.d
 
 $(LINK2 #whereToGo, linkName)
 ...
 ...
 ...
 $(ANCHOR whereToGo)
 ...
 ...
 ...
 


Uhm... I'm not sure where ANCHOR macro is defined... I can't find it.
The macro would expand to something like:

<a name="name" id="id"></a>

but I'm not sure where this line is supposed to be.
If i write something like:

/**
 * <a name="name" id="id"></a>
 * foo description bla bla bla
 * ...
 * ...
 */

void foo()
{
    ....
    ....
}

the link generated by CandyDoc is *AFTER* function foo definition:

(immagine this is CandyDoc documentation)

void foo();
foo description bla bla bla   <----- link points here
...
...
...

so, if you put somewhere this line:

$(LINK2 fooLink, foo)

once clicked, the browser will point to:

foo description bla bla bla

instead of (which i'd prefer)

void foo()
foo description bla bla bla
...
...

Luca.
Nov 29 2008
parent Morusaka <morusaka inwind.it> writes:
I think I've find a way to make it work (with CandyDoc at least)

I've definied the following macro:

/**
  * Macros:
 * DDOC_PSYMBOL = <a name="anchor$0" id="$0"></a><span
class="currsymbol">$0</span><script>explorer.outline.addDecl('$0');</script>
 */

and when I want a link to some definition, I've to write a line like this:

// immagine you want to link to opEquals
 /**
  *
  * See_Also:
  * $(LINK2 #anchoropEquals, opEquals)
  */
Nov 29 2008