This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
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