如何在 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 页面只是一个简短的，没有子句，而是一个查看完整代码的链接，普通的 cmets 解释了子句。

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

Answer 1

我第二次尝试解决它涉及创建一个新文件，即原始 PROLOG 源的副本，但使用 doxygen 格式的 cmets，并将 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 header file。

---

不好。手动将 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 = 否

  INPUT = README.md groups.dox source.pl

  EXTRACT_ALL = 是

  EXTRACT_STATIC = 是

  FILE_PATTERNS = *.pl *.prolog *.swipl

  FILTER_PATTERNS = *.pl="dox4pl"

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