[OpenAjaxIDE] Change the tag name for <returns>?

[Jon Ferraiolo]

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