如何正确格式化 class 实例引用

Question

我有这篇文档：

 /**
 * This method creates an import job for the given @arg item
 *
 * The default implementation should be suitable for most needs,
 * it'll create an instance of @class ImportProjectJob
 *
 * @return a job that imports the project
 */
virtual KJob* createImportJob(ProjectFolderItem* item);

然而 @class 不应该像这样使用并且在 doxygen 中没有像 @instanceof 这样的东西。我应该如何格式化它？

Answer 1

在 Doxygen 的 automatic link generation rules 下，如果某些文档文本与已记录的 class 的名称相匹配，并且该文本使用 interCaps 命名风格，则 Doxygen 会自动将该文本转换为 link 到该文档页面。因此，如果您只使用 "ImportProjectJob"，Doxygen 会发现 class（如果已记录）并将该文本转换为 link。

但是如果您的 class/function 不使用 interCaps 命名，您可以通过 @ref:

显式 link 到一个记录的实体

 * The default implementation should be suitable for most needs,
 * it'll create an instance of @ref ImportProjectJob

仅供参考：@arg 用于启动函数参数定义列表。类似于：

@arg @c AlignLeft left alignment.
@arg @c AlignCenter center alignment.
@arg @c AlignRight right alignment

您要查找的是 @p，它是用于引用参数名称等的内联格式。

Answer 2

只需使用 @ref 而不是 @class 并记录声明它的 class。

通常（默认情况下，即当 AUTOLINK_SUPPORT 为 YES 时），甚至不需要显式引用它。 Doxygen 会在检测到名称时自动 link 它。

顺便说一下，您对 @arg 的使用并不符合预期。使用 @p 进行内联引用，使用 @param 记录方法参数。

 /**
  * @brief This method creates an import job for the given @p item
  *
  * @details The default implementation should be suitable for most needs,
  *   it'll create an instance of ImportProjectJob
  *
  * @param item this is a folder item
  *
  * @return a job that imports the project
  */
 virtual KJob* createImportJob(ProjectFolderItem* item);

这是声明 ImportProjectJob 的地方：

 /**
  * @brief short desc of the class
  * 
  * @details A long description
  */
 class ImportProjectJob : public KJob
 {};

如何正确格式化 class 实例引用

How to properly format a class instance reference

c++

documentation

doxygen