[mercury-users] Custom declarations and preprocessors.

[Peter Schachte]

On Fri, Apr 14, 2000 at 03:31:45PM +1000, Tyson Dowd wrote:

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

It seems to me that directives should be reserved for formal, parsable,
statements to the compiler.  If you're just going to put english text in
quotes, a directive is not really appropriate.

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

You are ignoring another implementation option:  give the Mercury tokenizer
and parser an optional argument to tell it to hold onto comments.  The
compiler would probably not use this feature, but other tools could.  I
think this would give you most of the advantages of your approach, as well
as most of the advantages of using comments.

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

perl has plenty of failings, but it's (currently) a lot easier to use for
text processing than Mercury.

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

Why would you want to read interface files, if you have hyperlinked, nicely
formatted, readible reference documents?

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

An attitude shift will be necessary to get people to adequately document
their modules, in any case.  Having good tools to produce nicer looking
documents and useful cross referencing info will be a bit of a motivation
either way.  The question is, after they're motivated, how easy and
comfortable can you make it to use these features?

A few more advantages of putting documentation in comments which you
overlooked:

- Existing doc is written as comments.  Being able to generate decent
  looking documents without having to change existing modules is a very
  worthy goal.  There's quite a lot of uniformity in the Mercury library
  source code that can be exploited to produce nice looking documents.

- Forcing people to put their text and markup in a string adds new
  headaches, like remembering to double all quotes, and remembering to escape
  certain characters.  Strings are not good for long runs of text (as
  Mercury's C interface illustrates).

- It's error-prone for the same reason.  It's too easy to screw up a long
  string, and get reams of syntax error messages.  Comments, particularly
  %end-of-line comments, are much less likely to get screwed up.

- You don't have to modify the compiler to make use of documentation in
  comments.  You can even use existing language-agnostic tools, such as
  listings, to do this.

- People are used to writing documentation in comments (at least the people
  who do write documentation ;-).  If you can capitalize on natural
  commenting and documenting conventions, you'll have a much easier time
  getting people to use this sort of tool.

- I think something like

        % This predicate reorders the frobats within the dinglehopper in
        % order to achieve maximum woozelation.

  just looks a lot better than

        :- doc("This predicate reorders the frobats within the dinglehopper
                in order to achieve maximum woozelation.").

  Remember:  documentation is not only important when looking at it on
  hardcopy or in some fancy tool.  It's also important in your text editor
  while you're coding, so it should be readable as written (this is one
  problem I have with some literate programming tools:  they make pretty
  output, but really ugly source files).


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