Doxygen 不会自动链接到带有未记录名称空间中的参数列表的 C++ 函数

Question

我正在尝试通过指定参数为函数的特定版本生成 link。如果我只使用简单的函数名称 fn()，那么 Doxygen 会自动 links 到函数的一个版本。如果我包含参数，则不会生成 link。

Doxygen 说我应该能够 link 使用以下任一形式：

<functionName>"("<argument-list>")"

<functionName>"()"

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

完整示例如下所示 (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 版本和配置：

$ 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

感谢@albert，我意识到函数引用需要在一行中。但是后来回完整版代码的时候又发现了一个问题

原来是在命名空间中导致的问题。

普通函数名称 fn() 自动link编辑为函数的一个版本。

如果包含参数，则不会生成 link。

但是如果有命名空间注释，那么所有版本的函数引用都会生成一个link.

完整示例如下所示 (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

Doxygen 不会自动链接到带有未记录名称空间中的参数列表的 C++ 函数

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

c++

documentation

doxygen