This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: generating a reference manual from source code
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
------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org