OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] Grouping methodparams.

Richard Quadling wrote:
> On 20/02/2008, Stefan Seefeld <seefeld@sympatico.ca> wrote:
>> Richard Quadling wrote:
>>> Hi.
>>> I am using methodsynopsis and have some parameters which are optional.
>>> But, there is a pair of parameters that have to go together.
>>> e.g. function(param1 [, param2 [, param3, param 4]])
>>> Here params 3 and 4 are to the function, but must both be present.
>>> Either 1, 2 or 4 params. Never 3 params.
>> I don't think this is currently possible, and I'm not sure adding
>> support for this is appropriate. The whole set of <synopsis> tags is to
>> reflect language artifacts as far as syntax is concerned, not to express
>> semantic constraints on top of that.
>> Norm indicated he didn't want docbook to incorporate more than a minimal
>> set of modeling vocabulary. There is a whole lot of other things to be
>> added if docbook were to expand into that modeling direction. (There is
>> no 'type synopsis', for example.)
>> May be an extension 'profile' could be created for such things ? <hint/>
> I'm not sure I understand you. Does anyone know of any other APIs
> documented using Docbook? I would really like to see how others have
> handled this.

(For the record, I was referring to Synopsis: 
http://synopsis.fresco.org, which is a tool with similar features to 
doxygene. It's about the only one, though that can generate DocBook output.)

As to your actual question: yes, I believe it would be better to list 
this as a set of functions with different signatures (an overload set in 
C++). For example:


This wasn't generated from docbook, but it could easily be.
(One funcsynopsis can hold more than one funcprototype.)

> Our current solution is to provide multiple methodsynopsises.

Exactly. I think this is the right thing to do.



       ...ich hab' noch einen Koffer in Berlin...

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]