如何在 Prolog 中使用 Doxygen

Question

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

起初我只是想包含一个 "external and unknown" 文件，但正如 doxygen 用户所知，如果它找不到有用的（已记录的）函数，它就不会打印任何东西。

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

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

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

我的第一个（几乎）成功的方法在同时使用 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 页面只是一个简短的页面，没有子句，但是 link 可以看到完整的代码，解释条款的正常评论。

为什么这不适用于纯 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 两次。但是可以记录这些功能。使用此配置：

输入 = 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 = NO

INPUT = README.md groups.dox source.pl

EXTRACT_ALL = YES

EXTRACT_STATIC = YES

FILE_PATTERNS = *.pl *.prolog *.swipl

FILTER_PATTERNS = *.pl="dox4pl"
现在您可以运行您的 doxygen 就像您通常使用其他语言一样。

如何在 Prolog 中使用 Doxygen

How to use Doxygen with Prolog

c

doxygen

prolog