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

Lori Hylan-Cho lorihc at aptana.com
Wed Sep 10 10:44:01 PDT 2008


FWIW, <return-types> and <return-type> are what we use in our current ScriptDoc XML format.

From: ide-bounces at openajax.org [mailto:ide-bounces at openajax.org] On Behalf Of Jon Ferraiolo
Sent: Wednesday, September 10, 2008 1:12 PM
To: ide at openajax.org
Subject: [OpenAjaxIDE] Change the tag name for <returns>?


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/966b8006/attachment-0001.html 


More information about the IDE mailing list