[mercury-users] Custom declarations and preprocessors.

[Manuel Hermenegildo]

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

Yes, implementation is one issue. But the other is what I was trying
to describe in the message, i.e., that I find it useful to mix the
documentation and the actual declarations:

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

This approach makes a lot of sense to me in the context of other LP
languages. Perhaps in the context of Mercury one could do it the other
way around: write something like the declaration above inside a
comment and have a preprocessor that generates from it the actual
type/mode/etc. declarations and filters out the comments. But this
would force always passing the programs through the preprocessor
before compiling.

 > 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

This is great! (you should post it somewhere) 

But again, the point of the lpdoc approach is that these are at the
same time the comments that generate the documentation >and< the
declarations (assertions, in the general sense) that the compiler uses
to optimize programs, check them for correctness, introduce run-time
tests, perform static debugging, etc. You only need to write each bit
of information once. 

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