Doxygen not auto-linking to C++ function with argument list in an undocumented namespace

Question

I am trying to generate a link to a specific version of a function by specifying the arguments. If I just use the plain function name fn() then Doxygen auto-links to one version of the function. If I include the arguments then no link is generated.

Doxygen says I should be able to link using either of these forms:

1. <functionName>"("<argument-list>")"
2. <functionName>"()"

https://www.doxygen.nl/manual/autolink.html

The full example is shown below ( Run.hpp ):

// Copyright (c) 2021 Graphcore Ltd. All rights reserved.
/** \file
 *  Functions for recurrent neural networks (RNN).
 */

#ifndef popnn_Rnn_hpp
#define popnn_Rnn_hpp


/** Create state tensor to be used in all recurrences of the RNN. 
 *
 * TESTING:
 *
 * The default createOutputTensor() generates a link. But none of
 * the versions below do.
 * See createOutputTensor(int graph, const int params,
 *                  unsigned numShards,
 *                  const int debugContext)
 *
 * See createOutputTensor(int graph, const int params,
 *                  unsigned multiple, unsigned numShards,
 *                  const int debugContext)
 *
 * Or all on one line: createOutputTensor(int, const int, unsigned, unsigned, const int)
 *
 */
void createInitialState();


/** Create tensor.
 *
 * \param graph           Graph object.
 * \param params          The RNN parameters.
 * \param numShards       The number of shards to be used.
 * \param debugContext    Debug information.
 *
 * \return Tensor of shape  {timeSteps, batchSize, outputSize}.
 */
void createOutputTensor(int graph, const int params,
                   unsigned numShards,
                   const int debugContext);

/** Create tensor with size. 
 *
 * \param graph           Graph object.
 * \param params          The RNN parameters.
 * \param multiple        Integer multiple of standard output tensor.
 * \param numShards       The number of shards to be used.
 * \param debugContext    Debug information.
 *
 * \return Tensor of shape  {timeSteps * multiple, batchSize, outputSize}.
 */
void createOutputTensor(int graph, const int params,
                   unsigned multiple, unsigned numShards,
                   const int debugContext);

#endif // #ifndef popnn_Rnn_hpp

Doxygen version and configuration:

$ doxygen --version
1.9.2

$ doxygen -x
# Difference with default Doxyfile 1.9.2
PROJECT_NAME           = "Poplar and PopLibs"
OUTPUT_DIRECTORY       = ./doxygen
INPUT                  = ./include
GENERATE_LATEX         = NO

Answer 1

Thanks to @albert I realised the function references need to be on a single line. But then I found another problem when I went back to the full version of the code.

Turns out that the problem is caused by being in a namespace.

The plain function name fn() is auto-linked to a version of the function.

If the arguments are included then no link is generated.

But if there is a namespace comment, then all versions of the function reference generate a link.

The full example is shown below ( Run.hpp ):

// Copyright (c) 2021 Graphcore Ltd. All rights reserved.

/// Namespace comment needed to generate cross-references
namespace rnn {

/** Create state tensor to be used in all recurrences of the RNN.
 *
 * The default createOutputTensor() generates a link. But none of
 * the versions below do.
 *
 * See createOutputTensor(int graph, const int params, unsigned numShards, const int debugContext)
 *
 * See createOutputTensor(int graph, const int params, unsigned multiple, unsigned numShards, const int debugContext)
 *
 */
void createInitialState();


/** Create tensor.
 *
 * \param graph           Graph object.
 * \param params          The RNN parameters.
 * \param numShards       The number of shards to be used.
 * \param debugContext    Debug information.
 *
 * \return Tensor of shape  {timeSteps, batchSize, outputSize}.
 */
void createOutputTensor(int graph, const int params,
                   unsigned numShards,
                   const int debugContext);

/** Create tensor with size.
 *
 * \param graph           Graph object.
 * \param params          The RNN parameters.
 * \param multiple        Integer multiple of standard output tensor.
 * \param numShards       The number of shards to be used.
 * \param debugContext    Debug information.
 *
 * \return Tensor of shape  {timeSteps * multiple, batchSize, outputSize}.
 */
void createOutputTensor(int graph, const int params,
                   unsigned multiple, unsigned numShards,
                   const int debugContext);

} // namespace rnn