Re: DOCBOOK: Re: documenting an API: RFE

[Stefan Seefeld <seefeld@sympatico.ca>]

Norman Walsh wrote:

> | * 'type' seems to name types, not describe them. What
> |    about a 'typesynopsis' to actually define specific types ?
> 
> Can you show me an example of what you'd like to put in a type synopsis?

imagine code such as

typedef int MyInt;
enum FooBar { FOO = 0, BAR = 1};

I'd like to document that, i.e. the code could contain comments such as

// MyInt is a special integer type used to...
typedef int MyInt;

// FooBar represents the foobar of...
enum FooBar
{
// FOO signifies...
FOO = 0,
// BAR signifies 'not FOO'
BAR = 1
};

and I want to translate that into a document that lists the definition 
(purpose, usage, etc.) of the above types and constants. I want this 
documentation to be at the same level as class definitions 
(classsynopsis etc.) for example.

> | * 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') ?
> 
> I suppose. The funcsynopsis stuff was one of DocBook's few forays into
> modeling. After years of requests, we built a classsynopsis element to
> model object oriented languages in a similar way. As a general rule, we've
> tried to avoid modeling in DocBook and there are days when I wish we hadn't
> done either funcsynopsis or classsynopsis :-)

yeah, the current situation looks a bit inconsistent, or at least
unfinished. An example showing how to document APIs would really
help. Having used texinfo for this purpose a number of times, I see a
number of useful features that could be implemented with appropriate
stylesheets, such as the (semi-)automatic generation of indexes for
types, constants, functions, etc.)

> | * again for 'constant': a 'constsynopsis' to contain constant definition
> 
> What sort of definition?

see above. I think UNIX man pages could use these, for example to
contain the definitions for errno codes, or signals, or...

> | * a 'modulesynopsis' to define 'contexts', 'scopes', 'packages' or
> |    whatever this may be called in the various programming languages
> 
> There's already an RFE for package markup. And a longstanding action
> item on me to investigate. The problem is that there many different,
> conflicting notions about what a package is.

Indeed, but as you repeatedly said you didn't want docbook to become
a modeling language, I didn't think it is that important to attach
specific semantics to 'package', beside defining sort of a
context/scope.

> Examples of what you have in mind would be useful.

again, if I have (C++) code defining a namespace, and in that
namespace some other expressions I want to document, I'd like
to be able to document the namespace itself (it's purpose, domain,
etc.) and then put stuff into it. I admit that packages are for
my purposes the least urgent, as I can just map them to 'sections',
though it would be nice to attach a *little* more meaning to it.

Regards,
		Stefan