PlDoc does not work with aliased reexported predicates?

[Julio Di Egidio]

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]

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]

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]

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]

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]

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]

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