[mercury-users] Custom declarations and preprocessors.

[Ralph Becket]

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

If you wanted to be formal about it, one might write

:- promise (double([], [])).
:- promise all [X, Xs, Y, Ys]
	(double([X | Xs], [Y | Ys]) <=> X = 2 * Y, double(Xs, Ys)).

but now we might as well have exposed the source code.  Your
comment above is an informal gloss describing the properties of
the implementation, though, which is usually more useful.  The thing
is that the comment is just that and I'm quite happy with the existing
obvious separation between declarations and glosses.

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

Sure - I just have objective taste!

> 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).

As I say, I'm an old fashioned sort.  Give me a tags file and I'm a
happy programmer.  But if there's demand for more sophisticated
documentation extraction tools then go for it.

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