[ docbook-RFEs-1998852 ] Provide a mechanism to group parameters.

[SourceForge.net <no...@so...>]

RFEs item #1998852, was opened at 2008-06-20 15:07
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=384107&aid=1998852&group_id=21935

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: DocBook
Group: v5.0
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Richard Quadling (razorsedgeuk)
Assigned to: Norman Walsh (nwalsh)
Summary: Provide a mechanism to group parameters.

Initial Comment:
Hello.

My name is Richard Quadling and I am part of the PHPDOC team. A small part, not lead or editor.

We use Docbook 5 as our documentation standard and we have a small tool which converts the XML into our required formats.

There is a change that we would like to make to Docbook. Not significant, but would help us and probably other API documentation teams.

The addition we would like is to introduce is a new parent tag for methodparam (and probably other params).

Currently we can use choice="opt" against a single methodparam, but if the API says something like this ...

function x(int param1 [, string param2, float param3 [, array param4, array param5 [, boolean param6]]])

then we cannot easily document this. 

Our current solution is to have multiple methodsynopsis which get rendered as ...

int function x(int param1)
int function x(int param1, string param2, float param3)
int function x(int param1, string param2, float param3, array param4, array param5)
int function x(int param1, string param2, float param3, array param4, array param5, boolean param6)


The suggestion is to allow something like this ...

<methodsynopsis>
    <type>int</type>
    <methodname>x</methodname>
    <methodparam>
        <type>int</type>
        <parameter>param1</parameter>
    </methodparam>
    <methodparamgroup choice="opt">
        <methodparam>
            <type>string</type>
            <parameter>param2</parameter>
        </methodparam>
        <methodparam>
            <type>float</type>
            <parameter>param3</parameter>
        </methodparam>
        <methodparamgroup choice="opt">
            <methodparam>
                <type>array</type>
                <parameter>param4</parameter>
            </methodparam>
            <methodparam>
                <type>array</type>
                <parameter>param5</parameter>
            </methodparam>
            <methodparamgroup choice="opt">
                <methodparam>
                    <type>boolean</type>
                    <parameter>param6</parameter>
                </methodparam>
            </methodparamgroup>
        </methodparamgroup>
    </methodparamgroup>
</methodsynopsis>

We can then amend our rendering engine to provide grouped optional paramaters.

I would see <methodparamgroup choice="xxx"> having the same options as <methodparam choice="xxx">, though I think anything other than opt would be redundant.

I think other param types that could benefit from this : <funcparamgroup> maybe.

I hope this makes some sense.


Kind regards,

Richard Quadling.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=384107&aid=1998852&group_id=21935