[mercury-users] Custom declarations and preprocessors.

[Tyson Dowd]

On 14-Apr-2000, Ralph Becket <rbeck at microsoft.com> wrote:
> Response to Tyson's comments:
> 
> > 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.
> 
> I'm not sure I want this integrated into the language.  It increases
> the burden on later compiler writers and is entirely orthogonal to
> what the comiler is there for.

It should probably be just part of the implementation, or an add-on 
to the language.  I agree that making it part of the core language
isn't such a great idea.  But a standard add-on would be nice.

However, someone might have a FANTASTIC idea for some custom
declarations that they write a nice implementation of, and EVERYONE
agrees is absolutely wonderful and should be integrated into the
implementation and/or language at once for the good of all mankind.

If there is a custom declarations facility in Mercury, chances are they
will have used it, and we can experiment with integration into
implementations straight away.

Also, many many many places write custom little-languages for doing
particular domain specific work (e.g. people who do a lot of COM
programming in Mercury have a bunch of shortcuts to help them do this
faster).  They often expand this stuff out using a pre-processor.
If this facility was available, they might simply choose this syntax
as it is more uniform with the rest of the language.  For people working
on it, they have what appears to be a nice tightly integrated system.

My aim is to make it easier to experiment with new declarations (for
whatever purpose you want).  And if your experiment is a roaring success
perhaps get it integrated into the development system somewhere.

Often people writing these things are good at what they do, but not so
good at writing parsers, pre-processors and other bits and pieces to get
their work up and running.  Once you give them some way to easily grab
everything with :- foobar(.....) and turn it into some data structure
they are happy with, they can run with the ball quite quickly. 

The change I'm considering is allowing the compiler to ignore your
declarations (with a compiler option) and to provide some sample code
for writing Mercury source processors.

For documentation an argument can be made that putting documentation
inside a special little language you put inside the comments of the
program is the Right Way To Go.  However for any other sort of
declaration it probably isn't.  I don't think that structured
documentation is such a special case that we should exclude it from
using decls.

> > - Easier to implement (don't have write crappy perl regular 
> > expressions
> >   to parse Mercury, just re-use existing Mercury parsers).
> 
> Solution: (a) the PERL (or something more sane) records the line
> numbers where comments start/end; (b) the Mercury parser spots the
> surrounding declarations/clauses; (c) we just match up the line
> numbers.  Easy!

Not as easy as 
	(a) use term_io library



> > - Easier to incorporate language information from other declarations 
> >   (you're just parsing terms anyway)
> 
> See above.
> 
> > - 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). 
> 
> Yes, but you have to update the compiler, rather than the doc.
> processing tools. 

Depends how you re-used the compiler source.

I would like to split off the Mercury front end one day so that you can
write tools that use it without having the rest of the compiler
involved.

> Moreover, when developing I really don't want a
> compilation to fail/generate spurious warnings because my comments
> aren't in the official format.

You already get compilation errors and spurious warnings if your
comments aren't in the official format.

For example, consider this comment:

	/* here's a comment I forgot to terminate....

These decls are no different.  Don't change them and you won't 
get any errors. 

> > - 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).
> 
> No, anything the compiler can use like this should be in a bona fide
> declaration, like `promise' declarations.

The compiler can use human written text intended for human consumption
to generate documented code.  Emacs uses this convention in elisp quite
nicely to allow you to write user documentation for your hooks.  

I'm not a fan of the "if you can't write a comment in logic, you
shouldn't write it at all" school of thought.  

> > - 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.
> 
> I agree, but most commenting is much too informal for the compiler.

Yes.  And that kind of commenting is fine.  But sometimes you want some
more formal documentation system.

This is not supposed to replace normal comments.  It's an additional
system when you want to be able to auto-generate various forms of
documentation.

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

Interfacing with other languages that support documentation systems.
(e.g. if you have source browsers that kind of thing).

Interfacing with a language that has undergone a transformation to
appear in Mercury (the :- doc can tell you exactly what the 

This is particular useful if you say auto-generate a .int file for a
binary only object (e.g. no original source).  A COM DLL or even a CORBA
object might tell you what the original IDL was for each construct in
the :- doc documentation.

> 
> > - Directives don't get stripped out by pre-processors.  
> > Comments might.
> 
> That's fine - I draw a distinction between formal statements of the
> semantics of my program and the informal comments intended to convey
> intention, purpose etc. to other programmers.

I draw another distinction -- 

> 
> > - Documentation plays a nice role in interpreter/query based systems, 
> >   and documentation directives are easy to implement in these systems.
> 
> I would have thought that, e.g., source level debuggers get you 90% of
> what you want here for 10% of the effort.

So what?  You're doing the work anyway to make pretty HTML documents.
Inserting that same information in other places is hardly difficult.

> > 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.
> > 
> I agree.  I like the idea of promise declarations for stating
> properties and invariants in a formal manner.  Comments are
> more of a gloss.

However, well written documentation intended for humans still has an
important place!
 
> > - You don't need to mess around with teaching Mercury tools about it
> 
> Yes!  And you're at less risk of tying yourself into something
> that's a pain to implement and may be rarely used.

If we all stayed home every day and watched TV instead of writing code
we'd reduce that risk too.

However, we'd also reduce the risk of writing something useful and
great that everybody wants to use.

I proclaim right here and now -- I'm interesting in people extending
Mercury in weird and wonderful ways with custom systems to do things.
If people want to make them official parts of the language they'll need
to do a lot of convincing.  But writing :- declarations seems like a
nice way to go.

Another proposal was to use something other than :- for "unofficial" 
declarations. 

> > 	- 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 
> 
> Speaking with my IDEs-are-for-kiddies hat on, I personally don't
> have any problem working with things just as they are...  In fact,
> I find literate coding styles harder to read, if anything.

That's a matter of taste.  A lot of people use IDEs.  A lot of people
use emacs, which could easily use this kind of information too.

> > 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.
> 
> I know I sound like a luddite, but this sounds like the path to
> madness and divorce.  I fear an explosion of poorly thought out
> ad-hoc documentation schemes...

I think you should go to your Y2k bunker RIGHT NOW before things get
really out of control!

-- 
       Tyson Dowd           # 
                            #  Surreal humour isn't everyone's cup of fur.
     trd at cs.mu.oz.au        # 
http://www.cs.mu.oz.au/~trd #
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------