How to use Doxygen with Prolog - c

Question

I was struggling trying to make doxygen work with prolog.
At first I was only trying to include an "external and unknown" file, but as doxygen users know, it won't print a thing if it can't find useful (documented) functions.
Searching stackoverflow for both tags gives no single answer, and so I decided to ask, even if I already solved the puzzle, so people will have a hit in case of search.
I will let this question here, as people can suggest simple workarounds, and we may learn a bit more about the subject, but I'll use it to register my own answer after some (hard) efforts. Thanks.
To explain where I did start:
My first (almost) successful approach worked fine in a program that used both C and PROLOG.
It almost worked because latter on I saw this approach would not work in a PROLOG only project.
Anyway, what I did was simply add this
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
And PROLOG code would look like:
/**
* #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 */
This would work because C would create the site anyway, and PROLOG page would be just a brief, no clauses, but a link to see the complete code, with normal comments explaining the clauses.
Why this doesn't work for a pure PROLOG project? And how to do that?

Answer 1

My second attempt to solve it involved the creation of a new file, a copy of the original PROLOG source, but with comments in doxygen format, and converting PROLOG clauses in something C-like.
Call the source source.pl and the second copy source.dox. You would write the PROLOG program as you usually do, using doxygen before the first occurrence of each clause, atom, module, etc.
Then cp source.pl source.dox and edit source.dox converting all clauses in something like:
/**
* \file source.pl
* \ingroup GroupUnique
*/
/**
* \ingroup GroupUnique
* \brief Defining factorial module
*/
module(fatorial, [fatpl/2]);
This takes time and are prone to errors, but it was a workaround. Problem is that doxygen now lists source.pl twice. But the functions can be documented. Use this configuration:
INPUT = README.md groups.dox source.pl source.dox
You need to keep source.pl because it is there the real source to be seen. And source.dox would be more like a C header file.
Not good. The work to transform manually a source.pl into a source.dox led me to write my own compiler (well, technically a filter, that uses only lexical tokens).
The program is available open source at github:
https://github.com/drbeco/doxygenprolog
and is cited here in the official pages among other filters: doxygen helpers
And a little note here, in the official SWI-Prolog site:
SWI-Prolog news
To make doxygen work with an unknown language you need:
Install this filter in someplace PATH can find.
Edit your doxygen .cfg to have:
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"
Now you can run your doxygen as you normally do with other languages.