Re: [docbook-apps] Grouping methodparams.

[Stefan Seefeld <seefeld@sympatico.ca>]

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:

http://boost.org/libs/python/doc/v2/class.html#class_-spec-ctors

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.

Regards,
		Stefan

-- 

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