[mercury-users] Custom declarations and preprocessors.

[Ralph Becket]

>  > > In fact, in lpdoc we even
>  > > mix comments and the actual type/mode declarations all the time:
>  > > 
>  > > :- pred double(+X,-Y) :: int * int # "@var{Y} is twice @var{X}".
>  > 
>  > This seems pretty reasonable.  The part between the :: and 
> the # is pretty
>  > clearly parsable.  I still have reservations about the text part,
>  > mainly because I think it'll get clumsy for predicates with a
>  > longer description.  There's usually a lot more to be said about a
>  > predicate than this. 
> 
> Note that this is not meant to be just a comment: this IS the type and
> mode declaration. I.e., the idea is not to add the possibility of
> describing type/mode/etc. information in comments but rather to be
> able to add comments to the type/mode/etc. declarations.  Such
> combined declarations should be visible both to the documenter and to
> the (low-level) compiler. 

:- 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.  We don't really
need a comment.  However, when we get something more complicated, such
as
        % preceding_boundary(SepP, String, I) returns the largest index J =<
I
        % 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.

:- func preceding_boundary(pred(char), string, int) = int.
:- mode preceding_boundary(pred(in) is semidet, in, in) = out is det.

preceding_boundary(SepP, String, I) =
    ( if I < 0 then
        I
      else if SepP(string__unsafe_index(String, I)) then
        I
      else
        preceding_boundary(SepP, String, I - 1)
    ).

then writing the promise declarations becomes trickier and they would
arguably be more opaque to the reader.  Also, the comment attached to the
code above is way more formal than most one sees.

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
argue that in the tutorial case, you don't want to expose the reader to
the raw documentation.  Often, tutorials have a narrative and a suite of
examples that usually would get in the way of the programmer who just
wants the documentation.  So I think tutorial stuff should either occur
in a separate file or in a separate part of the source file, at which
point it becomes harder to see how the various tools being suggested can
help.

Cheers,

Ralph
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------