[mercury-users] Custom declarations and preprocessors.

[Ralph Becket]

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.

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

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

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

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

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

Can you explain more?

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

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

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

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

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

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

Ewwww!

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

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