DOCBOOK: documenting an API: RFE

[Stefan Seefeld <seefeld at sympatico dot ca>]

hi there,

I'm (again) trying to figure out how to document
APIs using docbook. I'v written a tool that parses
source code into an 'Abstract Syntax Tree':

http://synopsis.sf.net

, but up to now I have not been able to represent
the result adequately in docbook, so the tool only
provides formatters for other formats such as html,
texinfo, etc.

I'v been looking into the available docbook markup
elements, but either the right elements are missing
or they are not really suitable for the purpose:

I'd like to document types, variables, constants,
functions, etc. But while some of them seem to be
supported (there are elements for 'classsynopsis'
and similar), others are not. Here is a list of elements
I miss. I'd very much appreciate if others could either
confirm that there is nothing semantically similar, or
how I could document these things instead:

* 'type' seems to name types, not describe them. What
  about a 'typesynopsis' to actually define specific types ?

* same for 'variable': what about a 'variablesynopsis' (or 'varsynopsis') ?
  And, while we are at it: what is special about a 'field'
  (docbook's name for 'member variables') ? If there was a
  generic 'variable' element, couldn't 'fieldname' be considered
  a specialized 'variable' (or then 'varname') ?

* again for 'constant': a 'constsynopsis' to contain constant definition

* a 'modulesynopsis' to define 'contexts', 'scopes', 'packages' or
  whatever this may be called in the various programming languages

Any feedback would be highly appreciated. I'd like to either find
out how to 'correctly' represent these things in docbook, or
understand better what is missing so I could submit an RFE.

Thanks,
		Stefan