[mercury-users] Custom declarations and preprocessors.

[Dominique de Waleffe]

To add some comments from the real world[*] :-)

Having used quite a few languages and tools over the years, it has rarely
been the case that one language could be used in isolation from others in
making even small modules to be integrated into larger projects. Very often
it is needed to integrate very different idioms into one module (say Mercury
or Prolog or Lisp or ... code, XML examples, XML DTD's, Lex scripts,
Makefiles, shell scripts,....). And all of these aspects must be documented
as a whole if to be kept consistent otherwise, one part is updated and the
other is not, resulting in a final mess that is best thrown away...

To achieve that sort of objective, language specific add-ons like :-doc()
directives are not useful. The best approach is to use the LitProg tools and
there, the simpler the better. I've been using nuweb for several years and
consistently, the documentation and code have been:
 -) readable (both in printed form and editable form [since nuweb requires
only the minimum annotations])
 -) maintainable because all aspects could be found in one central place
with cross refs,
 -) more easily transmitted to others because of the same centralisation,
 -) of better quality because of shifting to explaining the reasoning behind
the code.

Yes, having one LitProg tool containing all your sources makes you loose
usage of some language specific tools but so far the advantage is still to
the LitProg approach.

So in conclusion:

:-doc() directives may be useful but they do not give any incentive to write
good documentation, further it is very difficult to expose complex stuff in
that sort of comments. That is best done using other tools like LaTeX...

:-doc directives are language specific whereas real project integrate many
different langauges and aspects which are best documented as a whole.

LitProg approach encourages one to write useful documentation and the best
tools are the simplest and language agnostic.

D.

[*] We're currently completing the implementation of  a workflow server for
a customer. The approach combines Petri net theory, XML representation for
processes and protocols, Java code for the client. The whole server is
written in Mercury.





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