Here is the current official state of the spec:
* We currently have a <returns> element
* The schema says there can be at most one <returns> element for each
<method> element
In recent discussion, we have decided to allow multiple <returns> elements
to support scenarios such as:
<method name="create" scope="instance">
<description>Creates a Gears object of the given class.</description>
<parameters>
<parameter name="className" required="true" datatype="String">
<description>The class to create.</description>
<options>
<option value="beta.database" />
<option value="beta.localserver" />
…
</options>
</parameter>
<parameter name="options " required="false" datatype="Object">
<description>An associative array of property values to
set.</description>
</parameter>
</parameters>
<returns paramName="className" paramValue="beta.database"
datatype="Database">
<description>An instance of the Database class.</description>
</returns>
<returns paramName="className" paramValue="beta.localserver"
datatype="LocalServer">
<description>An instance of the LocalServer class.</description>
</returns>
…
</method>
Therefore, we need to change the schema some, minimally to allow multiple
elements that provide return information. Here are 3 options:
(1) Just allow multiple <returns> elements. However, this approach has the
big disadvantage of being inconsistent with the rest of the spec where we
have a unified approach to singular and plural elements.
(2) Define plural and singular elements for return values. Here are some
options:
(a) <returns> and <return paramName= paramValue= datatype=>...</return>
(b) <returnTypes> and <returnType paramName= paramValue=
datatype=>...</returnType>
(c) <return-types> and <return-type paramName= paramValue= datatype=> ...
</return-type>
I like 2a the best and 2b second-best. What does everyone else think?
Jon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://openajax.org/pipermail/ide/attachments/20080910/9d74977b/attachment.html