c - 如何在 Prolog 中使用 Doxygen

Question

我一直在努力让 doxygen 与 prolog 一起工作。

起初我只是想包含一个“外部和未知”文件，但正如 doxygen 用户所知，如果它找不到有用的(已记录的)函数，它就不会打印任何东西。

在 stackoverflow 上搜索这两个标签没有给出单一答案，所以我决定问一下，即使我已经解决了这个难题，这样人们在搜索时就会有收获。

我会在这里提出这个问题，因为人们可以提出简单的解决方法，我们可能会更多地了解这个主题，但经过一些(艰苦的)努力后，我会用它来记录我自己的答案。谢谢。

---

解释一下我是从哪里开始的:

我的第一个(几乎)成功的方法在同时使用 C 和 PROLOG 的程序中运行良好。

它几乎成功了，因为后来我发现这种方法在仅 PROLOG 的项目中不起作用。

无论如何，我所做的只是添加这个

INPUT = README.md groups.dox c-and-pl.c c-and-pl.pl
FILE_PATTERNS = *.pl
EXTENSION_MAPPING += pl=c
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
SOURCE_BROWSER = YES

PROLOG 代码看起来像:

/**
 * @file cpl.pl
 * @ingroup GroupUnique
 * @brief CPL - C calls Prolog (Prolog module)
 * @cond SKIPPROLOG
 */

 /* brief explanation in a normal (non-doxygen) comment */
 clause(A) :- 
     rule(X),
     test(A, X).

 and(so, on).

 /** @endcond */

这是可行的，因为 C 无论如何都会创建站点，而 PROLOG 页面只是一个简短的，没有子句，而是一个查看完整代码的链接，解释条款的正常注释。

为什么这不适用于纯 PROLOG 项目？以及如何做到这一点？

Answer 1

我第二次尝试解决它涉及创建一个新文件，原始 PROLOG 源的副本，但带有 doxygen 格式的注释，并转换 PROLOG 子句在 C-like 中。

调用源代码source.pl和第二个副本source.dox。您可以像往常一样编写 PROLOG 程序，在每个子句、原子、模块等第一次出现之前使用 doxygen。

然后 cp source.pl source.dox 并编辑 source.dox 将所有子句转换为如下内容:

/**
 * \file source.pl
 * \ingroup GroupUnique
 */

/**
 * \ingroup GroupUnique
 * \brief Defining factorial module
 */
module(fatorial, [fatpl/2]);

这需要时间并且容易出错，但这是一种解决方法。问题是 doxygen 现在列出了 source.pl 两次。但是可以记录这些功能。使用此配置:

INPUT = README.md groups.dox source.pl source.dox

您需要保留 source.pl，因为它是可以查看的真正源代码。而 source.dox 更像是一个 C 头文件。

---

不好。将 source.pl 手动转换为 source.dox 的工作促使我编写了自己的编译器(嗯，技术上是一个 filter，仅使用词汇标记)。

该程序在 github 上开源:

https://github.com/drbeco/doxygenprolog

并在其他过滤器的官方页面中被引用:doxygen helpers

还有一点注意，在 SWI-Prolog 官方网站上: SWI-Prolog news

要使 doxygen 使用未知语言，您需要:

• 在 PATH 可以找到的地方安装这个过滤器。
• 编辑您的 doxygen .cfg 以具有:

  OPTIMIZE_OUTPUT_FOR_C = NO

  INPUT = README.md groups.dox source.pl

  EXTRACT_ALL = YES

  EXTRACT_STATIC = YES

  FILE_PATTERNS = *.pl *.prolog *.swipl

  FILTER_PATTERNS = *.pl="dox4pl"

• 现在您可以像通常使用其他语言一样运行您的 doxygen。