IDE Issue 10

From MemberWiki

Jump to: navigation, search

IDE Issue 10: returnType or returnTypes

Introduction

During the IDE phone call on 06Dec2007 (http://www.openajax.org/member/wiki/IDE_Minutes_2007-12-06), there was discussion about whether we should allow multiple return types or only a single return type. The Aptana XML file format allows for multiple return types.

Jon's proposed resolution

See the following related issues:

While my personal inclination is to "go along with Aptana" on various file format issues because of their expertise and real-world experience in expressing JavaScript APIs in XML, on this issue I am proposing the other option. The reason is consistency with how we treat function parameters. Right now, a function parameter can only have one type, such as "boolean", "integer", "array", or "object", and complex types are achieved by specifying either "object" or "any". For consistency, we should take the same approach with return values. If the return value can be any of multiple types (e.g., either a string or an object), then here are the available options:

  • The return type can specified as "any", where supplemental documentation provides details (e.g., only a string or an object will be returned)
  • The return type can be specified as a QName, but we need to add a fallback return type (just as has been proposed in IDE Issue 7 with parameters).
  • Down the road, the industry might define a standard for JSON Schema, in which case we can extend our metadata format by adding a new element, something like <datatype name="<QName>" schema="<uri>/>, which is placed at the top of the metadata file to associate a JSON Schema with a custom datatype.

Here is some proposed markup: 

<api...>
  <class...>
    <method...>
      ...
      <returns [type=""] [fallbackType=""]>
        <description>
      </returns>
    </method>
  </class>
</api>

where:

  • 'type' and 'fallbackType' are as proposed for IDE Issue 7
  • I show a <description> as a child element to <returns>, whereas Aptana has an independent element <return-description> because it seemed more natural after reorganizing the tagnames.
Retrieved from "http://www.openajax.org/member/wiki/IDE_Issue_10"
Personal tools