This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Re: documenting an API: RFE


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



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]