FW: DOCBOOK: DocBook 4.0: ClassSynopsis

[Rudi Chiarito <rc@cloanto.com>]

-----Original Message-----
From: Rudi Chiarito 
Sent: Thursday, January 13, 2000 21:44
To: 'docbook@lists.oasis-open.org'
Subject: RE: DOCBOOK: DocBook 4.0: ClassSynopsis

> If you have any comments, please send them to the list as soon
> as possible.  I expect to package up DocBook V4.0beta1 sometime
> next week.

I'm sorry if my reply is just a "few" weeks late, but I was really busy in
the past weeks. I noticed that DB V4.0beta1 hasn't showed up yet, so I'm
posting my comment.

What I would really like to see supported is Design by Contract(1), the
design pattern introduced by Bertrand Meyer and fully implemented in the
Eiffel language. Basically it's a mechanism that introduces preconditions,
postconditions and invariants. Although Eiffel is the only language that
offers native support for it (maybe Sather added it as an afterthought,
IIRC), there are some tools around for other languages: GNU Nana (C/C++),
jass (Java), iContract (Java), etc. I guess it's obvious that it belongs to
a class' documentation - even if it's useful for other purposes as well. The
fact that it's the most requested enhancement to Java on Sun's Java
Developer Connection maybe says something, too (the fact that Sun has got no
clue on how to implement it properly is a different issue and, all in all,
no surprise ;-]).

DbC could be supported by extending <classsynopsis>' content model with
<invariant> and <(field|method|constructor|destructor)synopsis>' with
<require> and <ensure> (precondition and postcondition, respectively).

I'm in charge for the documentation/development environment of a project
that is just getting started. We will be using IDL during the design phase
and I'm strongly advocating the adoption of DbC in order to increase
reliability and reduce development/QA times. I chose DocBook as the native
format for our documentation and it would be just great if contracting were
supported by the standard DTD, rather than through an extension of ours. My
hope is that in some way it'll help people document better their projects.

As an aside, another nice Eiffel convention that helps write better
documentation is grouping features (methods/attributes) by categories:
initialization (constructors), access, status setting, status report,
implementation (internal, private methods) and so on. How could I capture
that? I was thinking about something among the lines of <glossdiv> for
glossaries.

I guess this is all. :)

-- 
Signature not present. Press Control-Amiga-Amiga to continue.
"I'll be thy master: walk with me; speak freely" (Cymbeline Act V Sc. 5)

(1) A complete introduction to DbC is in this paper:
http://www.elj.com/eiffel/dbc/
(If you want to get quickly to the important part, read #5 - "A Missing
Link: The Contract")

Then there's an introduction by Bertrand Meyer himself:
http://www.eiffel.com/doc/manuals/technology/contract/

A couple more papers:
http://w3.one.net/~jweirich/java/javadbc/java-dbc.html
http://www.it.brighton.ac.uk/staff/rjm4/documents/dbc.tutorial.95.PDF