(core) Minor improvements to modes package documentation

Src-commit: 333dab37eadf4da7b7c8d6132df1cd9c7e0e3155

Author: danielaferreiro

core/lib/isomodes/isomodes.pl

@@ -15,7 +15,7 @@
 %% but then it says that the only error possible is for not 
 %% meeting the : var... what to do?
 :- modedef '?'(_).
-:- modedef '@'(A) + not_further_inst(A).
+:- modedef '@'(A) : nonvar(A) + not_further_inst(A).
 %% Only in older versions of standard? It is obsolete now.
 %% :- modedef '*'(_).
 

core/lib/modes/modes.pl

@@ -11,36 +11,38 @@
 % :- op(500,  fx,(++)). 
 % :- op(500,  fx,(--). 
 
-%% "ISO-like" modes
+%% "ISO-like" modes (Note that, if nonvar in calls is included in the
+%% parametric versions —not done since implied by instantiation type—
+%% then these modes are equivalent to parametric versions with P = term).
 :- modedef  +(A) :  nonvar(A).
 :- modedef  -(A) => nonvar(A). % This was : var(A). Could also imply steadfast.
-:- modedef --(A) :  var(A).     % Optional...
+:- modedef --(A) :  var(A).
 :- modedef  ?(_).
 :- modedef  @(A) +  not_further_inst(A).
 
 %% Useful input-output modes
 :- modedef in(A)  : ground(A) => ground(A).
 :- modedef ++(A)  : ground(A) => ground(A).  % Optional alias...
-:- modedef out(A) : var(A)    => ground(A).  % Take out the var/1 and no need for go?
-:- modedef go(A)              => ground(A).
+:- modedef out(A) : var(A)    => ground(A). 
+:- modedef go(A)              => ground(A).  % Note: used in foreign interface 
 
-%%% Other possibilities: 
+%% TODO: Other possibilities: 
 %% : mode for meta (also implies nonvar)
-%% ! mode for mutables
+%% ! mode for mutables (cf. fsyntaxplus)
 
 :- push_prolog_flag(read_hiord,on).
 
 %% Parametric versions of above
-%% TODO: hiord order? (Need to change in assrt 
-:- modedef  +(A,P) :  P(A).          % This was :: P(A) : nonvar(A).
-:- modedef  -(A,P)          => P(A). % This was :: P(A) : var(A).
-:- modedef --(A,P) : var(A) => P(A). 
-:- modedef  ?(A,P) :: P(A). 
+%% TODO: hiord order? (Need to change in assrt) 
+:- modedef  +(A,P) : (nonvar(A),P(A)).           % Obviously implies nonvar(A)
+:- modedef  -(A,P)          => (nonvar(A),P(A)).
+:- modedef --(A,P) : var(A) => P(A).
+:- modedef  ?(A,P) :: P(A).
 :- modedef  @(A,P) :: P(A) + not_further_inst(A).
 
-:- modedef in(A,P)  : (ground(A),P(A)) => ground(A). % This was :: P(A) : ground(A) => ground(A).
+:- modedef in(A,P)  : (ground(A),P(A)) => ground(A). 
 :- modedef ++(A,P)  : (ground(A),P(A)) => ground(A). % Optional alias...
-:- modedef out(A,P) : var(A) => (ground(A),P(A)).    % This was :: P(A) : var(A)    => ground(A).
-:- modedef go(A,P)           => (ground(A),P(A)).    % This was :: P(A)             => ground(A).
+:- modedef out(A,P) : var(A) => (ground(A),P(A)).
+:- modedef go(A,P)           => (ground(A),P(A)).
 
 :- pop_prolog_flag(read_hiord).

core/lib/modes/modes_doc.pl

@@ -10,10 +10,11 @@
 
 :- doc(module,"This package defines a number of @concept{modes} which
    are frequently useful in programs when describing predicates, e.g.,
-   via @decl{pred} assertions.  They correspond to the modes used in
+   via @decl{pred} assertions (or @em{doccomments}, see below).
+   They correspond to the modes used in
    many classical Prolog texts and code as documentation, with some
-   additions. However, these modes are actually syntactic sugar for
-   assertions, that can be checked either statically or
+   additions. In Ciao these modes are actually syntactic sugar for
+   assertions, so that they can be checked either statically or
    dynamically. Note that some of these modes use the same symbol as
    one of the @lib{basicmodes} and @lib{isomodes} packages (see
    @ref{Some basic Prolog modes} and @ref{ISO-Prolog modes}) but have
@@ -33,12 +34,12 @@
 @end{verbatim}
 
    (more precise than the above), expresses that @pred{is/2} should be
-   called with the second argument instantiated to an arithmetic
+   called with the second argument @em{instantiated} to an arithmetic
    expression and that on success it will bind the first argument to a
    number. The argument of a mode as above can be any property,
    including, e.g., regular types. 
 
-   The first declaration is equivalent to (it is in fact translated
+   The first declaration is equivalent to (and is in fact translated
    to) the assertion:
 
 @begin{verbatim}
@@ -60,11 +61,11 @@
 %  and binds the first argument with the result. 
 @end{verbatim}
 
-   and they are also translated to the corresponding assertions.").
+   which are also translated to the corresponding assertions.").
 
 :- use_package(modes).
 
-:- doc( + /1,"Argument should be bound (nonvar) when the predicate is
+:- doc( + /1,"The argument should be bound (nonvar) when the predicate is
    called. For example:
 
 @begin{verbatim}
@@ -74,12 +75,11 @@
    expresses that both arguments of @pred{>/2} should be bound when
    the predicate is called.").
 
-:- doc( + /2,"Argument should be instantiated when the predicate is
-   called to a term that has the indicated type or property. For
-   example:
+:- doc( + /2,"This argument should be @em{instantiated} when the
+   predicate is called. For example:
 
 @begin{verbatim}
-:- pred + > +.
+:- pred +arithexpression > +arithexpression.
 @end{verbatim}
 
    expresses that both arguments of @pred{>/2} should be bound to
@@ -91,60 +91,64 @@
    succeeds.").
 
 :- doc( - /2,"The argument is an output argument. It may be bound or
-   not at call time. It will be instantiated to a term that has the
-   indicated type or property if the predicate succeeds. For example,
-   this assertion:
+   not at call time. It will be @em{instantiated} to a term that has
+   the indicated type or property if the predicate succeeds. For
+   example, this assertion:
 
-@begin{verbatim} :- pred length(-list,-int).  @end{verbatim}
+@begin{verbatim}
+:- pred length(-list,-int).
+@end{verbatim}
 
    expresses that @pred{length/2} can be called in any mode, but on
-   output the second argument will be instantiated to a number and the
-   first one will be instantiated to a lit. Note that this does not
-   mean that the list will be ground, but rather that it will be a
-   complete list but whose elements can be any term, including
-   variables.").
+   output the second argument will be @em{instantiated} to a number
+   and the first one will be @em{instantiated} to a list. Note that
+   this does not mean that the list will be ground, but rather that it
+   will be a complete list but whose elements can be any term,
+   including variables (see the discussion of instantitation and
+   compatibility types in @ref{Declaring regular types}.").
 
 :- doc(-- /1,"The argument should be a free variable (i.e., unbound)
    when the predicate is called.").
 
 :- doc(-- /2,"The argument should be a free variable (i.e., unbound)
    when the predicate is called and will be bound to a term that has
-   the indicated type or property if the predicate succeeds.").
+   the indicated type or property in general, if the predicate
+   succeeds.").
 
 :- doc( ? /1,"No information is given on this argument.").
 
-:- doc( ? /2,"The argument can be a variable or, if it is intantiated,
-   it is to a term that is compatible with the indicated type or
-   property.").
+:- doc( ? /2,"The argument can be a variable or, if it is
+   instantiated, it is to a term that is @em{compatible} with the
+   indicated type or property.").
 
 :- doc( @ /1,"The argument will not be further instantiated, i.e.,
    will not be more instantiated than when the predicate is called.").
 
 :- doc( @ /2,"The argument will not be further instantiated, i.e.,
    will not be more instantiated than when the predicate is called,
-   and the term is compatible with the indicated type or property.").
+   and the term is @em{compatible} with the indicated type or property.").
 
 :- doc( in/1,"The argument is ground at call time.").
 
-:- doc( in/2,"The argument is ground at call time and is compatible
+:- doc( in/2,"The argument is ground at call time and is @em{compatible}
    with the indicated type or property.").
 
 :- doc(++ /1,"Same as @tt{in}: the argument is ground at call time.").
 
 :- doc(++ /2,"Same as @tt{in}: the argument is ground at call time and
-   is compatible with the indicated type or property.").
+   is @em{compatible} with the indicated type or property.").
 
 :- doc(out/1,"The argument is a variable when the predicate is called
    and will be ground if the predicate succeeds.").
 
 :- doc(out/2,"The argument is a variable when the predicate is called
-   and will be be bound to a ground term that is compatible with the
+   and will be bound to a ground term that is @em{compatible} with the
    indicated type or property, if the predicate succeeds.").
 
 :- doc( go/1,"The argument is ground by the predicate, if it
    succeeds.").
 
 :- doc( go/2,"The argument is ground by the predicate to a ground term
-   that is compatible with the indicated type or property, if the
+   that is @em{compatible} with the indicated type or property, if the
    predicate succeeds.").