Re: DOCBOOK: generating a reference manual from source code

[Stefan Seefeld <seefeld@sympatico.ca>]

Norman Walsh wrote:
> 
> / Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
> | ok, may be not all, and not individually. But it appears a bit inconsistent
> | (not self-contained) that there are entities to represent functions and entities
> | for classes, but none for 'other' types. Wouldn't it make sense to provide a
> | 'type' entity with similar 'meta data' such as 'typesynopsis' etc. ?
> 
> Yes, it is a bit inconsistent.
> 
> Here are some suggestions:
> 
> | module Input
> 
> This looks like a ClassSynopsis (role="idl", probably).

uh well, that's what I use for IDL interfaces.

> | {
> |   typedef unsigned long Device;
> 
> DocBook is lacking a tag for type definitions. Perhaps
> FieldSynopsis with a role attribute?

Hmm, given that this seems to be used for variable declarations, not
types, I'd suggest to add a flag (role ?) that indicates 'var' or 'type'.
But even that doesn't look exactly clean...

> |   struct Toggle
> |   {
> |     enum type {press, hold, release} actuation;
> |     unsigned long number;
> |   };
> 
> The best I can suggest is a MethodSynopsis (which is ugly tag abuse)
> with a role attribute.
> 
> |   union Payload switch (Discriminator)
> |   {
> |   case telltale: Bitset state;
> |   case key: Toggle kselection;
> |   case button: Toggle bselection;
> |   case positional: Position location;
> |   case valuation: Value val;
> |   };
> |   struct Item
> |   {
> |     Device dev;
> |     Payload attr;
> |   };
> |   typedef sequence<Item> Event;
> |   interface Filter
> |   {
> |     boolean handle(in Event e);
> |   };
> | };
> 
> Yuck. We're clearly unable to represent all of an IDL Synopsis.

I don't really think this is a problem specific with IDL.

> Can you enumerate all of the elements that would have to be added to
> describe an "IDLSynopsis" to the level of detail that a ClassSynopsis
> works for Java/C++/etc.?

classes and methods are just two important declarations that are worth being
documented. Here is (part of) the type system I use in my parsing tool to
represent language constructs. All objects in this hierarchy contain a variable
'language' and 'type', thus forming pairs like (IDL, module), (C++, namespace),
(python, module), (IDL, interface), (IDL, union), (C++, class), (C++, struct),
(IDL, typedef), (C++, enum), etc. You get the idea.
Using this scheme I seem to be able to capture the widest range of declarations
in a lot of languages while preserving all the necessary information.

> | entity set for types (which I could annotate with a 'role' attribute to encode the
> | specific name of the declaration or type, depending on the language, such as 'typedef',
> | 'enum', etc.).
> 
> Yes, that would seem like a reasonable compromise, except that I'm not
> sure how to handle the struct and union types without more hierarchical
> markup.

right. For example one general distinction would be between types and variables.
Type declarations include 'class', 'union', 'struct' (which often can be represented
as a single 'meta type' with various 'type' attributes). Variable declarations
include 'variable' (same as field ?), 'enumerator', 'constant', 'string literal'
and so on.
I don't see any possibility to generate an API reference manual without at least
some more annotation. Just 'role' really doesn't seem to suffice. And again, even
if I could force them into the existing type system in docbook, how could I generate
things like a 'type index', which is indispensible for larger reference manuals ?

Best regards,
		Stefan