How to use classsynopsis and friends

[Aristedes Maniatis <ari@ish.com.au>]

I'm confused about the purpose of classsynopsis, methodsynopsis and all the related elements. The documentation acknowledges that they are a mixture of modelling and documentation. But I'm hitting my head against a wall trying to use them for either.

As a model, they are clearly lacking many concepts inherent to something like javadoc. But that's OK, because I don't want a 1:1 mapping back to my code... I just want a nice way to output documentation. In my case, I'm modifying groovydoc output to spit out docbook instead of html, which gives me more options to tie into an existing docbook documentation workflow.

But as a documentation structure classsynopsis is also very lacking. It cannot contain common structural elements like <para> or <variablelist> so I'm very limited in formatting documentation elements. My docs contain lists, ulinks, xref and code samples (<programlisting>).

Should I just discard classsynopsis and friends as a well intentioned but ultimately dead-end bit of docbook, and go back to boring old sections, lists and other structures which are more expressive but have no semantic concepts of parameters, return types and more? Or am I missing the point of some other way to handle this?

By Google I've found zero examples of other people using classsynopsis.

Cheers
Ari


-- 
-------------------------->
Aristedes Maniatis
ish
http://www.ish.com.au
Level 1, 30 Wilson Street Newtown 2042 Australia
phone +61 2 9550 5001   fax +61 2 9550 4001
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Attachment: signature.asc
Description: OpenPGP digital signature