This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Reference markup for Java interfaces
- To: Docbook Mailing List <docbook at lists dot oasis-open dot org>
- Subject: DOCBOOK: Reference markup for Java interfaces
- From: Hans Ulrich Niedermann <ulrich at n-dimensional dot de>
- Date: Wed, 20 Sep 2000 03:57:42 +0200
Hi all!
I have question about how to mark up a reference of Java
interfaces. Perhaps you can enlighten me some :-)
We want to document Java interfaces that look like
public interface XMLProducer {
/** Set the <code>XMLConsumer</code> that will receive XML data. */
public void setConsumer(XMLConsumer consumer);
}
Now I wanted to mark these up properly in Docbook (4.1.2 XML) and
create a interface reference. What I ended up with after studying TDG
(paper and online) for hours was the following:
<reference>
<title>Sitemap interface reference</title>
<refentry id="whatever"><!-- FIXME -->
<refnamediv>
<refname>XMLProducer</refname>
<refpurpose>produces <acronym>XML</acronym> data</refpurpose>
</refnamediv>
<refsynopsisdiv>
<classsynopsis class="interface" language="java">
<ooclass>
<classname>MyProducer</classname>
</ooclass>
<oointerface>
<interfacename>XMLProducer</interfacename>
</oointerface>
<methodsynopsis>
<modifier>public</modifier>
<void/>
<methodname>setConsumer</methodname>
<methodparam rep="norepeat" choice="req">
<type>XMLConsumer</type>
<parameter moreinfo="none">consumer</parameter>
</methodparam>
</methodsynopsis>
</classsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This interfaces identifies classes that produce
...
which the <acronym>XML</acronym> data production is started.
</para>
</refsect1>
</refentry>
</reference>
But then I got some doubts and resulting questions:
1. Do I use <classsynopsis> correctly?
2. Is a <classsynopsis> within the <refsynopsisdiv> really what I
want?
3. How can I markup more information about the methods of the
interface (what it does, what the params mean, etc.)?
The only alternative I can think of would be using a reference
<chapter> with a <section> for each interface and a sub <section> for
each method where all <section>s adhere to some still-to-be-defined
markup standards. But this is not what I understand Docbook is
about. There must be a way to completely describe a Java interface in
Docbook.
Thanks a lot for any hint.
Uli