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

Jon Ferraiolo jferrai at us.ibm.com
Wed Sep 10 11:03:51 PDT 2008


Hi Lori,
Yes, I should have mentioned that ScriptDoc uses <return-types> and
<return-type>.

The reason I prefer <returns>/<return> and <returnTypes>/<returnTypes> is
for consistency with the rest of the OpenAjax Metadata language where we
are using camelcase instead of hyphens. For example, <eventHandlerPatterns>
(Library Metadata chapter), <childProperties>/<childProperty> (in the
Properties chapter), adn then <aboutMe> and <directoryTitle> (in the
Descriptive chapter).

Jon






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/6ccfaaa6/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: graycol.gif
Type: image/gif
Size: 105 bytes
Desc: not available
Url : http://openajax.org/pipermail/ide/attachments/20080910/6ccfaaa6/attachment.gif 


More information about the IDE mailing list