Re: FW: DOCBOOK: DocBook 4.0: ClassSynopsis

[Norman Walsh <ndw at nwalsh dot com>]

| What I would really like to see supported is Design by Contract(1), the
[...]
| 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).

What would the content models of <invariant>, <require>, and
<ensure> be?

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

If you have developed an extension, please post it.

| 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 think the best choice there would be putting the various synopses
in their own sections, rather than inside a classsynopsis (or perhaps
in addition to the classsynopsis).

<section><title>Initialization</title>

<constructorsynopsis>...</constructorsynopsis>

<para>...</para>

<constructorsynopsis>...</constructorsynopsis>
<constructorsynopsis>...</constructorsynopsis>

</section>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Men do not quit playing because
http://www.oasis-open.org/docbook/ | they grow old; they grow old
Chair, DocBook Technical Committee | because they quit playing.--Oliver
                                   | Wendell Holmes