[mercury-users] Custom declarations and preprocessors.

[Tyson Dowd]

On 13-Apr-2000, Ralph Becket <rbeck at microsoft.com> wrote:
> > From: Peter Schachte [mailto:schachte at cs.mu.OZ.AU]
> > 
> > > Anthony Senyard <anthls at cs.mu.oz.au> is working on a Mercury
> > > documentation tool that allows
> > > 
> > > 	:- doc(predname/arity, "Some comment about the predicate").
> > 
> > It seems more natural to me to put this kind of documentation 
> > in the source file as a comment...
> 
> I agree completely.  By all means come up with a comment-embedded
> mark-up language and, say, a documentation-extraction-tool-friendly
> coding style, but I can't see any advantage to extending the language
> itself with commenting directives (in fact, it'd be a royal pain).

While several people have said that they prefer putting this kind of
information in comments, I personally believe that directives are
the way to go.

Why?  Mostly because it simplifies implementing various things and
allows a much smoother path towards integration into the language.

- Easier to implement (don't have write crappy perl regular expressions
  to parse Mercury, just re-use existing Mercury parsers).

- Easier to incorporate language information from other declarations 
  (you're just parsing terms anyway)

- Your tools is more likely to handle of new Mercury features
  (since you based it on the compiler source it's pretty easy to
  update). 

- Your tool can be easily incorporated into the compiler to give it even
  more information -- e.g. inference results or imported module
  information (once the compiler starts reading the comments of the
  program, the embedded comments approach is just a pain).

- Your documentation language can be used by the compiler and other
  tools to embed documentation information in a variety of places
  (e.g. inside profiling data or inside debugging data).
  If you are going to check a declaration in any way, you should
  probably consider it part of the language.

- You can put `:- doc' into interface files quite nicely.  This is
  particularly nice in some foreign language interfacing scenarios.

- Directives don't get stripped out by pre-processors.  Comments might.

- Documentation plays a nice role in interpreter/query based systems, 
  and documentation directives are easy to implement in these systems.

The reasons for putting documentation in comments are (summarized
by me, a not so objective summarizer):

- Programmers find writing documentation in comments more natural.
	- Comments are called comments (and not documentation) for 
	  a reason.  Personally I've noticed sometimes programmers
	  write comments in comments, but documentation is very rare in
	  any part of the program.

- You don't need to mess around with teaching Mercury tools about it
	- Which is probably why three people have developed
	  such systems independently and never bumped into each
	  other.
	  Teaching Mercury tools about it can be done relatively
	  easily.  I was going to add a general mechanism so people can
	  play with their own declarations and when a full system is
	  developed they can 

At any rate, at the moment perhaps it would make formalized embedded
comment lovers happier to think of

	:- doc(......).

as shorthand for
	% doc(.......).

since I'm leaning at the moment at just writing code to allow user
nominated declarations to be ignored by the compiler.


Note that documentation is not the only use for this system.  Any
declarations you'd like to put into the your code, but have
ignored by the compiler, can be used too.  This might be nice if you are
building on top of Mercury or even writing multi-language programs.

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