[dbdoclet] Re: Generating real methodsynopsis markup?

Hi Michael,

the strict style does indeed generate "proper" classsynopsis-style =
markup - I missed this initially, although it is in the dbdoclet =
documentation.

In a larger context, I have been thinking that maybe Java API =
documentation should actually also use the reference markup instead of =
plain chapter/sect1 markup.

The end result would be something like this (with examples from dbdoclet =
documentation):

<reference id=3D"PACKAGE-1" xreflabel=3D"org.dbdoclet.doclet">
  <title>Package org.dbdoclet.doclet</title>
  <partintro><para>The package org.dbdoclet.doclet contains the =
following classes: ...</partintro>

  <refentry id=3D"CLASS-1-1" =
xreflabel=3D"org.dbdoclet.doclet.ClassDiagramManager">
    <refnamediv>
      <refname>Class ClassDiagramManager</refname>
      <refpurpose>The class ClassDiagramManager. (first sentence of =
JavaDoc class
description)</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <classsynopsis class=3D"class" language=3D"java">
        <ooclass>
          <classname>ClassDiagramManager</classname>
        </ooclass>
        <constructorsynopsis language=3D"java">
          <modifier>public</modifier>
          <methodname>ClassDiagramManager</methodname>
          <methodparam>
            <type>DocletOptions</type>
            <parameter>options</parameter>
          </methodparam>
        </constructorsynopsis>
      </classsynopsis>
    </refsynopsisdiv>
    <!-- ... -->
    <refsection>
      <title>Declaration</title>
      <para><literal>ClassDiagramManager</literal></para>
    </refsection>
    <refsection>
      <title>Description</title>
      <para>The complete class description.</para>   =20
    </refsection>
    <refsection role=3D"constructorlist">
      <title>Constructors</title>
      <refsection id=3D"CONSTRUCTOR-1-1-1">
        <title>ClassDiagramManager</title>
        <refsection>
          <title>Declaration</title>
          <para><literal>public ClassDiagramManager</literal></para>
        </refsection>
        <refsection>
          <title>Description</title>
          <para>Method description goes here.</para>
        </refsection>
      </refsection>
    </refsection>
    <!-- ... -->
  </refentry>
</reference>

<reference id=3D"PACKAGE-2" xreflabel=3D"org.dbdoclet.doclet.docbook">
<!-- and so on -->
</reference>

This is not a complete example, but I think you get the idea. The main =
thing is that there would be one reference per package, with one =
refentry per class/interface/exception. There would also be one =
refsection for constructors, another for fields, and another for =
methods. I think this is closer to the HTML that the JavaDoc tool =
produces.

I have been dabbling with a doclet that emits markup like this, but I =
would like to know if there is any chance of dbdoclet evolving in this =
direction before committing to developing that further.

If you are interested, I can supply a more comprehensive example. I am =
currently working on the PDF version of JSR-238 and I need to get a =
solution within a few weeks, so I probably need to hack something =
together, but I am willing to contribute the general design of this =
approach if you think it is feasible.

Best regards,
Jere

> -----Original Message-----
> From: dbdoclet-bounce@xxxxxxxxxxxxx
> [mailto:dbdoclet-bounce@xxxxxxxxxxxxx]On Behalf Of ext Michael Fuchs
> Sent: Thursday, March 10, 2005 12:22 AM
> To: Norman Walsh
> Cc: dbdoclet@xxxxxxxxxxxxx
> Subject: [dbdoclet] Re: Generating real methodsynopsis markup?
>=20
>=20
> Hello Norman,
>=20
> you can use the style "strict" to generate strict DocBook code.*
> *Therefore you have to set the property=20
> doclet.style.flavour=3Dstrict in=20
> your dbdoclet.properties file.
> Unfortunatley the command line option -styleflavour seems to=20
> be broken.
>=20
> I would prefer to introduce the strict style as the default=20
> style, but=20
> FOP crashes if something is much wider
> than the page width. Unfortunatley this  happens very often with long=20
> class names. The usage of programlisting
> is not because I don't like the DocBook tags.
>=20
> Regards
> Michael=20
>=20
> P.S. If you are interested, there is also a possibility to=20
> create your=20
> own style via XSLT.
>=20
> Norman Walsh schrieb:
>=20
> >Is it possible to generate real methodsynopsis markup? That is,
> >this:
> >
> >      <classsynopsis>
> >        <ooclass><modifier>public</modifier>
> >          <classname>DocumentBuilder</classname>
> >        </ooclass>
> >        <constructorsynopsis>
> >          <modifier>protected</modifier>
> >          <methodname>DocumentBuilder</methodname>
> >          <void/>
> >        </constructorsynopsis>
> >        <methodsynopsis>
> >          <modifier>public</modifier>
> >          <modifier>void</modifier>
> >          <methodname>reset</methodname>
> >          <void/>
> >        </methodsynopsis>
> >        ...
> >
> >instead of
> >
> >      <programlisting width=3D"75">package javax.xml.parsers;
> >
> >public abstract class <emphasis=20
> role=3D"bold">DocumentBuilder</emphasis> {
> >
> >  <emphasis>// Protected Constructors</emphasis>
> >  protected <emphasis role=3D"bold">DocumentBuilder</emphasis>();
> ><indexterm><primary>DocumentBuilder</primary></indexterm>
> >  <emphasis>// Public Methods</emphasis>
> >  abstract public DOMImplementation <emphasis=20
> role=3D"bold">getDOMImplementation</emphasis>();
> ><indexterm><primary>parse</primary></indexterm>  public void=20
> <emphasis role=3D"bold">reset</emphasis>();
> >
> >I patched an old version of dbdoclet to do it, but...
> >
> >                                        Be seeing you,
> >                                          norm
> >
> > =20
> >
>=20
>=20
>=20

Other related posts: