PlDoc with reexport

Help! PlDoc
1

Hi all,
I noticed a glitch of PlDoc with modules that reexports the predicates of another module with the reexport directive.
When showing the PlDoc page of the original module, the reexported predicates, even if correctly documented in the other module, are shown as undocumented.
See e.g. the PlDoc of mcintyre from the cplint pack
https://www.swi-prolog.org/pack/file_details/cplint/prolog/mcintyre.pl
that reexports cplint_util
https://www.swi-prolog.org/pack/file_details/cplint/prolog/cplint_util.pl
Why can’t PlDoc retrieve the documentation from the reexported module?

Best
Fabrizio

2

Hi,
I noticed a difference between doc_save/2 and doc_server/2 on how they render files: the latter seems able to document more predicates for the same source file.

For example, in cplint when I create the html for the various modules with (file gen_docs.pl in subfolder docs)

:- consult('../prolog/cplint_util').
:- consult('../prolog/pita').
:- consult('../prolog/mcintyre').
:- consult('../prolog/slipcover').
:- consult('../prolog/viterbi').
:- consult('../prolog/kbest').
:- consult('../prolog/pitaind').
:- consult('../prolog/lemur').

:- doc_save('../prolog/pita.pl',[doc_root('./pldoc'),index_file(pita)]).
:- doc_save('../prolog/mcintyre.pl',[doc_root('./pldoc'),index_file(mcintyre)]).
:- doc_save('../prolog/slipcover.pl',[doc_root('./pldoc'),index_file(slipcover)]).
:- doc_save('../prolog/viterbi.pl',[doc_root('./pldoc'),index_file(viterbi)]).
:- doc_save('../prolog/cplint_util.pl',[doc_root('./pldoc'),index_file(cplint_util)]).
:- doc_save('../prolog/kbest.pl',[doc_root('./pldoc'),index_file(kbest)]).
:- doc_save('../prolog/pitaind.pl',[doc_root('./pldoc'),index_file(pitaind)]).
:- doc_save('../prolog/lemur.pl',[doc_root('./pldoc'),index_file(lemur)]).


:- halt.

or with

:-doc_save(.,[]).

reexported predicates are not documented.
Instead with

?- use_module(library(pita)).
true.

?- use_module(library(mcintyre)).
true.

?- use_module(library(slipcover)).
true.

?- use_module(library(viterbi)).
true.

?- use_module(library(cplint_util)).
true.

?- use_module(library(kbest)).
true.

?- use_module(library(pitaind)).
true.

?- use_module(library(lemur)).
true.

?- doc_server(4010,[]).

reexported predicates get documented. Moreover, for module cplint_util, many predicates are not documented with doc_save/2, while they are with doc_server/2.

See

Best
Fabrizio

3

In turns out doc_save/2 processes an undocumented option include_reexported(Bool), which defaults to false. Adding this option as true indeed includes re-exported predicates. Possibly the default should change? Not sure, as it may duplicate the documentation. A module that merely combines functionality from other modules could have a header documentation that points at this while just linking to the documentation rather than duplicating it.

4

I agree, but currently if reexported predicates are not included, they appear as undocumented, which is ugly. I guess the best solution is what you propose, add a link to point to the documentation of the reexported module, maybe with a list of the reexported predicates (just name and parity).

However, there are problems also for modules that do not use reexport.
For example, for module cplint_util, I get the correct result only if I move the directory where the file is and from there I load the file and call doc_save(.,[]),

If I run it from folder docs, I get an access error while the folder is writable for me:

ERROR: /Users/fabrizio/.local/share/swi-prolog/pack/cplint/docs/gen_pldoc.pl:10:
ERROR:    open/4: No permission to open source_sink `'/index.html'' (Read-only file system)
Warning: /Users/fabrizio/.local/share/swi-prolog/pack/cplint/docs/gen_pldoc.pl:10:
Warning:    Goal (directive) failed: user:doc_save('../prolog/',[doc_root('./pldoc'),include_reexported(true)])

I had to make pldoc writable also by group and others.
If I use

:- doc_save('../prolog/cplint_util.pl',[doc_root('./pldoc'),index_file(cplint_util),include_reexported(true)]).

then the output documents only one predicate and not all the others, even if I remove include_reexported(true).

Best
Fabrizio

5

Other observations: doc_save(.,[]) with modules with reexported predicates, lists, under the header
" Re-exported predicates", all the reexported predicates and lists all the exported predicates as undocumented.
If I use doc_save(.,[include_reexported(true)]) does the same, without the header.
If I use

:- doc_save('mcintyre.pl',[doc_root('./pldoc_ind'),index_file(mcintyre),include_reexported(true)]).

then all the exported predicates are documented and all the reexported are not.

Best
Fabrizio

6

I cloned your current cplint and looked at gen_pldoc.pl. If I generalize this code a bit, all seems to work fine. Probably vital is to load library(pldoc) first, such that all documentation is properly processed while loading the sources. The index_file(File) is not needed for a single file. It determines the file name when documenting a directory.

Also pushed some cleanup for PlDoc, but probably none of this is really relevant. Mostly use more the file file handling libraries to simplify the code and make it more robust.

P.s. cplint does not load in the current git version. library(clpr) can no longer be loaded as library(clp/clpr). This was never needed as the clp subdir of the library was in the library search path.

gen_pldoc.pl 
:- use_module(library(pldoc)).
:- use_module(library(doc_files)).
:- use_module(library(filesex)).

:- initialization(gen_doc, main).

doc_file(cplint_util).
doc_file(pita).
doc_file(mcintyre).
doc_file(slipcover).
doc_file(viterbi).
doc_file(kbest).
doc_file(pitaind).
doc_file(lemur).

load_all :-
    forall(doc_file(File),
           ( directory_file_path('../prolog', File, Path),
             ensure_loaded(Path))).

gen_doc :-
    load_all,
    Opts = [ doc_root('./pldoc'),
             include_reexported(true)
           ],

    forall(doc_file(File),
           ( directory_file_path('../prolog', File, Path),
             doc_save(Path, Opts))).
7

Thanks Jan, this works perfectly, Thanks also for the bug report on cplint.

Fabrizio