[dbdoclet] Re: Generating real methodsynopsis markup?

Hello Jere,

it is possible to create a "reference" style, but it will take some time 
and I'm very busy with my "commercial" projects at the moment.
Please send me a complete prototype DocBook file for two or three 
classes and I will start as soon as possible.

Regards
Michael

Jere.Kapyaho@xxxxxxxxx schrieb:

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

Other related posts: