In doxygen documentation how to create a link to a specific line of a file

Question

There are several doxygen commands whose purpose is to create links in the documentation (@link, @ref).
I am currently using the @ref command to create a link to a custom file, written in a language not supported by doxygen (xml).
I would like to alter this link so that it points to a precise line in the file.
Is there a doxygen command that allows to do that ?

Rabb

Answer 1

I'm not sure that \ref or \link can do this. However, if they could, one problem of adopting this approach is that the links will become invalid if you change the contents of the file you are linking to without changing the link. This is one of the problems of separating source code and documentation.

Rather than linking to a particular line in another file why don't you include the particular part of the file you are interested in in the documentation? You could either:

• include the whole file with \include (there is also \includelineno) and just reference relevant parts of it in the text (e.g. "function xxx in the code below"), or
• include snippets of the file where you need to refer to them in the documentation using \snippet.

Edit: Alternatively, you could use the \dontinclude command which, together with the \line, \skip, \skipline, and \until commands allows you to include specific lines/blocks of a particular file. See the example in the \dontinclude documentation.

Wartow

Thanks for your suggestions. The \snippet command seemed promising, however it only works for code snippets from source files, while I want to show data from my xml resource file. I cannot add the tags identifying the snippet location to my xml file because doxygen-style comments would "break" it. The use of \include is smart as well, but it is a huge file and I do not want to include it every time (the documentation would be blotted by irrelevant data). However when I use a \ref to my file, I already reference relevant parts, as you suggest. I am just looking for an even better way. – Rabb

@wil No problem. I have also added a note on the \dontinclude command, which would be better for you than the \snippet command since it does not require any tags to be added to your resource file. However, according to the documentation it seems that this command only works on source files (I have not tested this, so am not sure if this is actually the case). You could also include the XML directly in your documentation. Failing this I'm afraid you may just have to live with using your \ref method. – Wartow

I tried the \dontinclude commands and it also works for xml files ! I have settled for this solution and set your answer as "accepted" :-) – Rabb

Thanks, glad I could help - knowing that you can document XML resource files in this way is very useful. – Wartow

Answer 2

One reliable way to do that is -- at the target line of the file you want to link to, in a Doxygen comment include an

/** \anchor  unique_anchor_string */

in a Doxygen comment. (You have to get Doxygen to process the above file.) Then you can use

/** \ref  unique_anchor_string  "Link Text" */

in another file to link to the anchor defined in the first file. Note that that only works if the target file is part of the list of files that Doxygen "consumes" when it runs (It will need the \file command if it is not already there.) The unique_anchor_string must be unique among the list of anchors in the files so consumed. This list includes anchors automatically created by Doxygen (you get to control the names) for things like pages, sections, subsections, etc..

Meperidine