From: SourceForge.net <no...@so...> - 2009-01-22 13:57:45
|
RFEs item #1998852, was opened at 2008-06-20 11:07 Message generated for change (Comment added) made by nwalsh 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.1 >Status: Closed Resolution: Accepted 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. ---------------------------------------------------------------------- >Comment By: Norman Walsh (nwalsh) Date: 2009-01-22 08:57 Message: Fixed in SVN, destined for V5.1 ---------------------------------------------------------------------- Comment By: Norman Walsh (nwalsh) Date: 2008-07-18 07:27 Message: Logged In: YES user_id=81663 Originator: NO The TC has accepted this issue and I've started a thread on the docbook list to discuss our proposed solution (which is to reuse 'group' for this purpose). ---------------------------------------------------------------------- Comment By: Richard Quadling (razorsedgeuk) Date: 2008-06-20 11:10 Message: Logged In: YES user_id=487909 Originator: YES I've attached an XML file to show the example better. Didn't realise SF wouldn't honour the intending. File Added: Example methodparamgroup tag.xml ---------------------------------------------------------------------- You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=384107&aid=1998852&group_id=21935 |