how to create a Doxygen link to the same file

2
votes

I would like to write a Doxygen comment that names the file in which the comment occurs. Rather than write the filename explicitly, I would like Doxygen to supply me with it. Thus, if I change the name of the file, or move some of the content into a different file, I don't need to change hard-coded instances of the name.

For a concrete example, let's say I'm adding comments to functions in array.hpp, and I want the comment for certain functions to say "This function should only be used within array.hpp." I want to be able to write

/**
 *  This function should only be used within @thisfile.
 */

where @thisfile is a Doxygen expression that translates into array.hpp within the file array.hpp.

I've looked at the Doxygen documentation, including "Automatic link generation/Links to files" and the entire "Special Commands" section, but I haven't found what I'm looking for. Does such functionality exist?

Note that essentially the same question was asked on the Doxygen mailing list a few weeks ago. It has not received any replies.

1
doxygen

1 Answers

1
votes

General

As far as I know such functionality does not exist out-of-the-box. But you can add it by configuring an INPUT_FILTER in your Doxyfile. The path to the file is passed as an argument to the filter by doxygen. This can be used by the filter to replace your keyword (for example @thisfile) with the path to the file.

Below I give an example how to implement this with bash. A solution for other shells or Windows should be quite similar.

Example for bash

  1. Write a short bash script infiltrate_filename.sh:

    #!/bin/bash
pathToScript=`pwd`"/"
sed -e "s:@thisfile:${1/$pathToScript/}:g" $1

    This script truncates the path to the file by the working directory. The resulting string is used to replace the keyword of your choice (here: @thisfile).

  2. Make your script executable: chmod +x infiltrate_filename.sh
  3. Set the INPUT_FILTER in your Doxyfile to INPUT_FILTER = ./infiltrate_filename.sh

That's it! 🎉 Now you can use @thisfile in your documentation blocks and it will be replaced by the path to the file. As the paths are relative to Doxygen's working directory they will automatically be linked to the file.

Notes

This solution assumes that the filter script is located in the working directory of doxygen (for example ~/my_project) and that the INPUT files are in subdirectories of the working directory (for example ~/my_project/src/foo/bar).

I have tested this example on a minimum working example. I am not a bash or sed expert. This solution may be improvable.