PlDoc does not work with aliased reexported predicates?

33 views
Skip to first unread message

Julio Di Egidio

unread,
Aug 20, 2016, 9:42:49 PM8/20/16
to swi-p...@googlegroups.com
Hello guys,

Unless I am missing something, PlDoc works fine with reexported predicates
(documentation for these appears at the bottom of the documentation for the
module that does the reexport), but it does not work if we alias the reexported
predicates, namely, it claims that the predicates (as per the aliases) are not
documented.

Of course, it works if we duplicate the docs from the reexported module to the
reexporting one then change the predicate names to their aliases, but this
duplication is of course not acceptable, so I am ending up not using aliases at all...

Julio

Jan Wielemaker

unread,
Aug 22, 2016, 4:34:04 AM8/22/16
to Julio Di Egidio, SWI-Prolog
On 08/21/2016 03:42 AM, Julio Di Egidio wrote:
> Hello guys,
>
> Unless I am missing something, pldocs works fine with reexported
If aliasing means using the `as ...` syntax, it makes a lot of sense not
to use it IMO. These things were added to simplify writing
compatibility libraries. In other contexts it is probably mostly
confusing. Documenting these is low priority as the emulated system is
hopefully documented :)

If you think it is important I'm afraid you need to do some hacking in
PlDoc. It is surely not impossible. I'm happy to merge a pull request
that adds this.

Cheers --- Jan


>
> Julio
>
> -- You received this message because you are subscribed to the
> Google Groups "SWI-Prolog" group. To unsubscribe from this group and
> stop receiving emails from it, send an email to
> swi-prolog+...@googlegroups.com
> <mailto:swi-prolog+...@googlegroups.com>. Visit this group at
> https://groups.google.com/group/swi-prolog. For more options, visit
> https://groups.google.com/d/optout.

Julio Di Egidio

unread,
Aug 22, 2016, 8:00:32 AM8/22/16
to swi-p...@googlegroups.com
On Monday, August 22, 2016 at 10:34:04 AM UTC+2, Jan Wielemaker wrote:
On 08/21/2016 03:42 AM, Julio Di Egidio wrote:
> Hello guys,
>
> Unless I am missing something, pldocs works fine with reexported
> predicates (documentation for these appears at the bottom of the
> documentation for the module that does the reexport), but it does not
> work if we alias the reexported predicates, namely, it claims that
> the predicates (as per the aliases) are not documented.
>
> Of course, it works if we duplicate the docs from the reexported
> module to the reexporting one then change the predicate names to
> their aliases, but this duplication is of course not acceptable, so I
> am ending up not using aliases at all...

If aliasing means using the `as ...` syntax,

Yes.

it makes a lot of sense not to use it IMO.

It might have to do with my present approach to module structuring:

In a "main" module:

:- module(mylib, [mylib_foo/1]).

:- use_module(mylib_sub).

mylib_foo
(Args) :-
    validate_etc_
(Args),
    mylib_sub
:foo_(Args).

And in the "sub"-module:

:- module(mylib_sub, []).

:- public foo_/1.

foo_
(Args) :-
   
...

And I document (pldoc) both the main and the sub-predicate in the
respective modules (because the sub-predicate is meant to be
an "unsafe" version that is available for maximum performance).

Then I was first trying to reexport the sub predicates, which seemed
more in line with the usual exporting patterns, i.e. exporting from the
main module all predicates meant for public use, safe and unsafe, but
the problem there is that without aliases the reexported names are
meaningless: namely I want mylib_foo_, not just foo_ !

But with aliases pldoc does not work (as I have explained), so
I have ended up not reexporting the sub-predicates at all.  If a user
wants the "unsafe" predicates, they will have to write mylib_sub:foo_

These things were added to simplify writing
compatibility libraries. In other contexts it is probably mostly
confusing. Documenting these is low priority as the emulated system is
hopefully documented :)

If you think it is important I'm afraid you need to do some hacking in
PlDoc. It is surely not impossible. I'm happy to merge a pull request
that adds this.

I wouldn't mind, but I'm not sure anymore that it's worth it: after all I am
not too dissatisfied with the solution I have ended up with, which I find
pretty clean despite maybe a bit unusual...

Your thoughts?

Julio

Jan Burse

unread,
Aug 22, 2016, 4:10:42 PM8/22/16
to SWI-Prolog
Hi,

If I remember well the following are the same, right?

:- module(foo, [bar/1]).
bar(_) :- ...
baz(_) :-

And:

:- module(foo, []).
:- public bar/1.
bar(_) :- ...
baz(_) :-

In both cases baz/1 is turned into a module private predicate.
This is a pitty that there is no private directive, and that
predicates that are not designated private or public, are
not package local in SWI-Prolog.

With package local one can solve to some extend the
problem that some predicates should have clients nearby
but nevertheless not be public. In Jekejeke Prolog I have
therefore introduce the private/1 directive.

Here is an exampe inside a package "pack"

:- module(mod, []).
:- use_module(submod).
:- public foo/1.
foo(_) :- priv(_), bar(_), ....
:- private priv/1.
priv(_) :- ...

:- module(submod, []).
/* no public and no private declaration here, hence package local */
bar(_) :- subpriv(_), ...
:- private subpriv/1.
subpriv(_) :-

As a result of the above setup in Jekejeke Prolog, the predicate
bar/1 can be used by the predicate foo/1, since mod and submod
are in the same package "pack", and the visibliity of bar/1 is
package local.

As a further result of the above setup in Jekejeke Prolog, the
predicates priv/1 and subpriv/1 can only be accessed inside
their module. This can be also done in SWI-Prolog by omiting
the private decalration for these predicates.

But to my current knowledge package local visiblity has not been
introduced in SWI-Prolog. Mostlikely it was also not present
in Quintus, at least I guess so. I have borrowed the idea of
package local predicates from Java.

Bye



Julio Di Egidio

unread,
Aug 22, 2016, 4:51:54 PM8/22/16
to SWI-Prolog
On Monday, August 22, 2016 at 10:10:42 PM UTC+2, Jan Burse wrote:
 
If I remember well the following are the same, right?

:- module(foo, [bar/1]).
bar(_) :- ...
baz(_) :-

And:

:- module(foo, []).
:- public bar/1.
bar(_) :- ...
baz(_) :-

Do you ever read the docs?  :)

No, public/1 just "Instructs  the cross-referencer  that the predicate  can be  called.
It  has no semantics."  Considering also that the public directive has no consequence
on pldoc either (the predicate is considered private with or without the public directive),
these two are essentially equivalent:

:- module(foo, [bar/1]).
bar(_) :- ...
baz(_) :-

And:

:- module(foo, [bar/1]).
:- public baz/1.

bar(_) :- ...
baz(_) :-

Julio

Anne Ogborn

unread,
Aug 23, 2016, 2:24:55 AM8/23/16
to Jan Burse, SWI-Prolog
I've found reexport useful for a different scenario.

We have some code that effectively does polymorphism. 
We have base code in module foo.
We create module bar, which largely does the same as foo, but changes a few things, by using
reexport/2 in module bar, and similarly with baz.

We can now import either bar or baz into mep and get a change in behavior, and in fact the selection of which happens based on a command line option.

I've also done this:
At The Elgin Works we have a bunch of small business units. As an incubator, we're always trying things.
Each of these has it's own product knowledgebase, with part, sku's , etc.

Often we don't care about the business unit, and wish to treat all of these as, effectively, multifile predicates. We have a bit of code that defines master predicates that 'farm out' to the business units. This code is in a 'elginworks' module, and is generated at load time by a declarative. Ultimately the business unit list comes from  a setting.

So we should be careful about making too many assumptions about how modules are used.


Jan Wielemaker

unread,
Aug 23, 2016, 4:03:37 AM8/23/16
to Anne Ogborn, Jan Burse, SWI-Prolog
On 08/23/2016 08:24 AM, 'Anne Ogborn' via SWI-Prolog wrote:
> So we should be careful about making too many assumptions about how
> modules are used.

That is a fair point to make. Modules are pretty versatile. I've
used and misused them in various weird ways :) Note that the low-level
API allows for much more than the de-facto standard high-level one.

That said, if anyone wants PlDoc to be smart about these things,
go ahead and change it ...

Cheers --- Jan
Reply all
Reply to author
Forward
0 new messages