PlDoc and foreign code

Help! PlDoc
1

Can I get PlDoc to slurp up predicate documentation comments for foreign predicates (i.e., written in C or C++ and registered using some variety of PL_register_*)?

I have a definition this, registered using the SWI-cpp2 macro PREDICATE:

PREDICATE (sf_sound_buffer_get_samples, 2)
/*
  %! sf_sound_buffer_get_samples(+SoundBuffer:blob_sfSoundBuffer, -Samples:list[int]).
  %
  % Get the array of audio samples stored in the buffer.
*/
{
     blah blah...
}

I would like for swipl to have access to such docstrings, through the usual channels such as the PlDoc browser, apropos, etc. It doesn’t seem like PlDoc deals with non-Prolog source files, or am I mistaken? Is there a recommended way to handle documentation for foreign predicates?

2

My “solution” to this problem is to document them in the Prolog file that loads the foreign module. It would not be very hard to add a parser for PlDoc comments in arbitrary (non-Prolog) files. But, it may be hard to find the source files and they may even not be there (i.e., you may only have the binary). Another option might be to add e.g.

PL_doc(Name, Arity, DocString)

Not sure that is any better than commenting in the Prolog file though. After all, many modules that involve foreign code also involve Prolog code and typically part of the foreign predicates are only there to support the public API in Prolog.

3

Thanks, that makes sense. And I just remembered that I have several dozen foreign predicates where the foreign code + doc string comment isn’t even in the foreign source files at all, because it comes from a macro!