[mercury-users] Custom declarations and preprocessors.

[Manuel Hermenegildo]

 > :- pred double(int, int).
 > :- mode double(in, out) is det.
 > 
 > :- promise all [X, Y] (double(X, Y) <=> X = 2 * Y).
 > 
 > Now this is easy to read and the compiler can use it. 

Agreed (although this is more verbose than what I wrote...). I don't
really want to get too much into the details because we do have
somewhat different ideas regarding how predicate modes, types, and
other properties should be described from how it is done in Mercury
and you are right of course to stick as much as possible to how things
are done now in Mercury. But, one point:

 > We don't really need a comment.  

Well, for example you may want to associate a different comment with
each mode.  E.g., in lpdoc/Ciao:

:- pred double(X,Y) : int  => int             
   # "@var{Y} is @var{X} times two".

:- pred double(X,Y) : list(int) => list(int)  
   # "Elements of @var{Y} are the elements of @var{X} times two".

Perhaps one would like to do something like that in Mercury? I don't
really know. But it seems to me that if you do this is a case where
you definitely want the comment as part of the declaration.

Regarding the overall comments such as:

 >        % preceding_boundary(SepP, String, I) returns the largest index J =<
 >        % in String of the char that is SepP and min(-1, I) if there is no
 >        % such J.  preceding_boundary/3 is intended for finding (in reverse)
 >        % consecutive maximal sequences of chars satisfying some property.
 >        % Note that I *must not* exceed the largest valid index for String.

It is really a matter of taste whether it is better to write them as
above, or as declarations:

:- comment( preceding_boundary(SepP, String, I), 

   "Returns the largest index J =< in String of the char that is SepP
    and min(-1, I) if there is no such J.  preceding_boundary/3 is
    intended for finding (in reverse) consecutive maximal sequences of
    chars satisfying some property.  Note that I *must not* exceed the
    largest valid index for String. 
   ").

(or :- doc(..).) The only thing is that comments complicate
implementation a bit: you cannot simply use the standard reader to get
them (unless you modify it, of course).

Also, I would argue that if you have a single 'mode' of use, then the
simplest thing to describe your predicate might be as (forgive me for
starting to get again somewhat off topic here, by using again
Ciao-style declarations):

:- pred preceding_boundary(SepP, String, I, O)
  
   : (pred(+char) + semidet) * string * int * term => int(O) + det 
   
   # "Returns the largest index J =< in String of the char that is
      SepP and min(-1, I) if there is no such J.  preceding_boundary/3
      is intended for finding (in reverse) consecutive maximal
      sequences of chars satisfying some property.  Note that I *must
      not* exceed the largest valid index for String.".

 > If we draw a distinction between documentation and tutorial, then just
 > looking at the comment in the code is what you want for the former.  I'd

I think there are three separate objectives:

1 - Documentation of the source code.
2 - Generation of a reference manual.
3 - Generation of a tutorial.

In agree the best way to write #3 is as a separate file/document. But
I think you can pretty much fulfill objectives 1 and 2 by adding to
the source a combination of declarations and traditional comments (the
latter for the implementation stuff that the reader of the reference
manual is not interested in).

Manuel

-- 

-----------------------------------------------------------------------------
herme at fi.upm.es                      | Manuel Hermenegildo                 
+34-91-336-7435 (Work)               | Facultad de Informatica, UPM
+34-91-352-4819 or 336-7412 (FAX)    | Universidad Politecnica de Madrid   
http://www.clip.dia.fi.upm.es/~herme | 28660-Boadilla del Monte, MADRID SPAIN
-----------------------------------------------------------------------------

--------------------------------------------------------------------------
mercury-users mailing list
post:  mercury-users at cs.mu.oz.au
administrative address: owner-mercury-users at cs.mu.oz.au
unsubscribe: Address: mercury-users-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-users-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------