[mercury-users] Custom declarations and preprocessors.

[Peter Schachte]

On Fri, Apr 14, 2000 at 11:32:03AM +0200, Manuel Hermenegildo wrote:
> 
> Peter makes some valid points: there are indeed advantages to literate
> programming using comments but there are also advantages to such
> comments being declarations.

Other than being easier to implement, which I concede, what are the
advantages of declarations over comments for plain text documentation?

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

Another example is the recent introduction of "field" names in Mercury type
declarations.  Clearly this is much better than having the same information
in a comment.  Where there's some clear, narrowly-defined intent behind some
documentary information, by all means use a declaration.  Pred and mode
declarations are really good because they have a clear semantics.  Likewise,
a formal description of integrity conditions on its arguments would be good
to have as a declaration.  But the paragraph describing the details of what
a predicate does, or the page of blather about a module, just don't seem
like declarations to me.

As you say, I guess it's a matter of taste.

BTW, I've written a Prolog-to-latex translator (in Prolog) that looks for
comments of the form

% double(+X, -Y)
% Y is twice X.

and spits out nice latex.  It automatically italicizes variable names in the
text, recognizing them from the argument list in the "prototype".  I took
the approach of trying to minimize the need for markup by recognizing common
idioms in documentation, like *stars* for emphasis and banner comments for
sectioning the document.  I found that worked quite well, as it produces
nice output while minimizing hard-to-read markup in the source file.

-- 
Peter Schachte                     True development puts first those that
mailto:schachte at cs.mu.OZ.AU        society puts last.
http://www.cs.mu.oz.au/~schachte/      -- Mahatma Gandhi 
Phone:  +61 3 8344 9166            
Fax:    +61 3 9348 1184            
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------