OpenAjax Metadata Specification API Metadata

From MemberWiki

Jump to: navigation, search

Notes:

This wiki page holds a portion of the latest internal editorial draft for what ultimately will become the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification.

Here is the proposed way for the IDE WG to edit this specification:

All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say DRAFT CONSENSUS, TENTATIVELY APPROVED or APPROVED) represents preliminary proposed text that requires further review and discussion.
Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
When an item has been deemed complete by the WG chair due to committee consensus, then the annotation APPROVED will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation DRAFT CONSENSUS or TENTATIVELY APPROVED will be placed at the end of given block of text (e.g., paragraph or bullet).

<--previous contents--^ next-->

1 3 API Metadata

[edit]

3 API Metadata

[edit]

Introduction

This chapter defines the OpenAjax Metadata XML grammar for the runtime JavaScript APIs (e.g., classes and methods) that are available for a given Ajax library.

While it is possible that Ajax libraries might choose to use this XML grammar as the original source documentation for its JavaScript APIs, in a more common scenario the Ajax library will use a different format such as JSDoc for API documentation within the original JavaScript files, and then supply a converter utility that converts the inline document comments into one or more OpenAjax Metadata files:

Original JavaScript files (with doc-comments inline) => CONVERTER => OpenAjax Metadata

Replace the above with a picture

[edit]

Feature overview

Proposed editorial strategy: This section would be concise and provide a bulleted list of the kinds of features that API metadata describes (e.g., classes, globals, interfaces, methods, properties, events, ...), with links to the elements that correspond to those features, and then the main body of the chapter would be the detailed reference section 2008-04-22: Draft consensus. Reasonable approach.

2008-04-29 Draft consensus: (Not sure where to put this, so putting this here for now) We decided that in IDE workflows the tool loads a set of metadata files and these files can reference the datatypes defined in other files, but for mashup workflows, each widget file is self-contained except for any dependencies that are explicitly listed by its <require> elements.

[edit]

Example

Need to update this example to show some recent decisions, such as distinguishing between fields and properties.

Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<api xmlns="http://openajax.org/metadata" version="...">
   <class name="libraryname.ClassName" superclass="Object">
       <constructors>
           <constructor scope="instance">
               <description>Constructor description</description>
               <parameters>
                   <parameter name="message" required="true" datatype="String">
                       <description>Parameter description</description>
                   </parameter>
               </parameters>
               <returnType datatype="Object">
                 <description>...</description> 
               </returnType>
           </constructor>
       </constructors>
       <properties> 
           <property name="propertyInstance" readonly="false" scope="instance" datatype="String">
               <description>Property description</description>
           </property>
           <property name="propertyStatic" readonly="false" scope="static" datatype="String">
               <description>Property description</description>
           </property>
       </properties>
       <methods>
           <method name="functionInstance" scope="instance">
               <description>Method description</description>
               <parameters>
                   <parameter name="param" required="true" datatype="String">
                       <description>Parameter description</description>
                   </parameter>
               </parameters>
               <returnType datatype="String">
                 <description>...</description>
               </returnType>
           </method>
           <method name="functionStatic" scope="static">
               <description>Method description</description>
               <parameters/>
               <returnType datatype="String"> 
                 <description>...</description> 
               </returnType>
           </method>
       </methods>
   </class>
</api>

[edit]

API metadata

Need to add a short intro

[edit]

The `<api>` element

2008-07-08 Draft Consensus: We agreed that all elements that can be used multiple times requires a plural version of the element, and that in all cases, the plurals are optional. Therefore, you can say either
<class>...</class>
<class>...</class>
or
<classes>
<class>...</class>
<class>...</class>
</classes>.
Tools must look for either (i.e., /class or /classes/class).

api_element = element api {
  api_content  &  api_attributes  &  foreign_nodes
}
api_content = (
  author_element*  &  authors_element*  &  class_element*  &  classes_element*  &  
  enum_element*  &  enums_element*  &  globals_element*  &  
  interface_element*  &  interfaces_element*  &  license_element?  &  
  mixin_element*  &  mixins_element*  &  namespace_element*  &  namespaces_element*  &
  descriptive_elements 
)
api_attributes = (
  getterPattern?  &  language?  &  setterPattern?  &  spec?  &  version?
)

JSDoc v2 allows @author on constructors, methods and properties. Shouldn't we allow it in our schema also so that JSDoc can be mapped into our format (even if few people will specify @author at such a fine level and even if tools will usually ignore this information)? Editorial note: updated schema to add authors/author to api element.

The <api> element is the root element of an API file.

The version attribute specifies the version number of the JavaScript libraries that are documented by this metadata file. (See the section titled "Version number attributes" within the "Compatibility" chapter for rules on version number attributes.) 2008-05-29: Tentatively approved

The spec attribute specifies the version number of the OpenAjax Metadata spec to which this metadata file conforms. (See the section titled "Version number attributes" within the "Compatibility" chapter for rules on version number attributes.) 2008-05-29: Tentatively approved

The language attribute specifies the programming language for which the API metadata applies. The default is "javascript", which indicates the various versions of the language whose standard is named "ECMAScript" (e.g., ECMA-262) but which is often referred to as "JavaScript". 2008-07-08: Tentatively approved. Agreed on "javascript" and that it is the default value for the attribute.

The getterPattern attribute specifies not yet written, is a substitution pattern which provides the function name for the getter function, available on <property>, <properties>, <api>, and <widget>.

The setterPattern attribute specifies not yet written, same as getterPattern, except this is for the setter..

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Subelements defined in this chapter

[edit]

Alias elements

[edit]

`<alias>`

alias_element = element alias {
  alias_content  &  alias_attributes  &  foreign_attributes
}
alias_content = (
  empty
)
alias_attributes = ( 
  name
)

The <alias> element can be used to specify an alternate name for an object that a tool might use during content assist. Typically, the alternate name is shorter and/or more understandable that the original name.

The name attribute specifies the name of the alias.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<aliases>`

aliases_element = element aliases {
  aliases_content  &  aliases_attributes  &  foreign_nodes
}
aliases_content = (
  descriptive_elements  &
  alias_element*
)
aliases_attributes = (
  name?
)

The <aliases> element holds zero or more <alias> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <aliases> element in case multiple <aliases> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Ancestor elements

[edit]

`<ancestor>`

ancestor_element = element ancestor {
  ancestor_content  &  ancestor_attributes  &  foreign_attributes
}
ancestor_content = (
  empty
)
ancestor_attributes = ( 
  datatype
)

The <ancestor> element describes not yet written

The datatype attribute specifies either the ancestor class name or ancestor interface name. The detailed description of the datatype attribute can be found in the Datatypes chapter. However, for the <ancestor> element, the value can only be the name of a class or interface and cannot be one of the core JavaScript datatypes (such as String or Object). Needs review: is this description correct?

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<ancestors>`

ancestors_element = element ancestors {
  ancestors_content  &  ancestors_attributes  &  foreign_nodes
}
ancestors_content = (
  descriptive_elements  &  
  ancestor_element*
)
ancestors_attributes = (
  name?
)

The <ancestors> element holds zero or more <ancestor> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <ancestors> element in case multiple <ancestors> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Class elements

[edit]

`<class>`

class_element = element class {
  class_content  &  class_attributes  &  foreign_nodes
}
class_content = (
  alias_element*  &  aliases_element*  &  ancestor_element*  &  ancestors_element*  &  
  constructor_element*  &  constructors_element*  &  event_element*  &  events_element*  &  
  field_element*  &  fields_element*  &  mix_element*  &  mixes_element*  &  
  method_element*  &  methods_element*  &  property_element*  &  properties_element*  &  
  descriptive_elements  &  compatibility_elements
)
class_attributes = (
  name  &  superclass?  &  visibility?  &
  getterPattern?  &  setterPattern?  
)

The <class> element describes a JavaScript class.

The name attribute specifies the absolute object name using JavaScript dot notation for the class, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript class (i.e., has an appropriate constructor function).

The superclass attribute specifies not yet written.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

DRAFT CONSENSUS: All of the black text above reflects draft consensus from our previous discussion.

[edit]

`<classes>`

classes_element = element classes {
  classes_content  &  classes_attributes  &  foreign_nodes
}
classes_content = (
  descriptive_elements  &  
  class_element*
)
classes_attributes = (
  name?  &  getterPattern?  &  setterPattern?  
)

The <classes> element holds zero or more <class> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <classes> element in case multiple <classes> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Constructor elements

[edit]

`<constructor>`

constructor_element = element constructor {
  constructor_content  &  constructor_attributes  &  foreign_nodes
}
constructor_content = (
  exception_element*  &  exceptions_element*  &  parameter_element*  &  parameters_element*  &  
  returnType_element*  &  returnTypes_element*  &  
  descriptive_elements  &  compatibility_elements
  # Research the above, make consistent with the spec  
)
constructor_attributes = (
  visibility?
)

The <constructor> element describes a constructor method. A constructor can be described by multiple<constructor> element, in which case the different <constructor> elements can be used to specify different parameter and return value alternatives.

The scope attribute describes not yet written and can have values instance or static.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

DRAFT CONSENSUS: All of the black text above reflects decisions from previous discussion.

[edit]

`<constructors>`

constructors_element = element constructors {
  constructors_content  &  constructors_attributes  &  foreign_nodes
}
constructors_content = (
  descriptive_elements  &  
  constructor_element*
)
constructors_attributes = (
  name?
)

The <constructors> element holds zero or more <constructors> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <constructors> element in case multiple <constructors> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Event elements

[edit]

`<event>`

event_element = element event {
  event_content  &  event_attributes  &  foreign_nodes
}
event_content = (
  parameter_element*  &  parameters_element*  &  returnType_element*  &  returnTypes_element*  &  
  descriptive_elements  &  compatibility_elements
  # Research the above, make consistent with the spec  
)
event_attributes = (
  name
)

The <event> element describes not yet written, but meant for toolkit-specific event systems. For OAHub, use topics instead.

The name attribute specifies the name of the event.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion. 2008-08-05 DRAFT CONSENSUS: We reviewed this element again and decided to keep it, along with parameters and return type. Jon added 'name' after the phone call as this was an apparent oversight and sent email asking people to make sure this wasn't a mistake.

[edit]

`<events>`

events_element = element events {
  events_content  &  events_attributes  &  foreign_nodes
}
events_content = (
  descriptive_elements  &  
  event_element*
)
events_attributes = (
  name?
)

The <events> element holds zero or more <event> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <events> element in case multiple <events> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Exception elements

[edit]

`<exception>`

exception_element = element exception {
  exception_content  &  exception_attributes  &  foreign_nodes
}
exception_content = (
  descriptive_elements  &  compatibility_elements
)
exception_attributes = (
  datatype?
)

The <exception> element describes not yet written

The datatype attribute not yet written, but we decided that it can be either an ECMAScript core datatype such as String or a classname

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<exceptions>`

exceptions_element = element exceptions {
  exceptions_content  &  exceptions_attributes  &  foreign_nodes
}
exceptions_content = (
  descriptive_elements  &  
  exception_element*
)
exceptions_attributes = (
  name?
)

The <exceptions> element holds zero or more <exception> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <exceptions> element in case multiple <exceptions> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Field elements

[edit]

`<field>`

field_element = element field {
  field_content  &  field_attributes  &  foreign_nodes
}
field_content = (
  option_element*  &  options_element*  &  
  descriptive_elements  &  compatibility_elements
  # Research the above, make consistent with the spec  
)
field_attributes = (
  name  &   datatype?  &  visibility?  &  scope?  &
  datatype_supplemental_attributes  # FIXME: Is this correct?
  # <scope>?
)

2008-07-29 Added options/option as child elements because it seemed like an oversight in the schema. Need to ask WG to review this change.

The <field> element describes not yet written, but represents data values on JavaScript objects that can be retrieved or set via direct assignment (i.e., without requiring a getter or setter function)

The name attribute specifies not yet written.

The datatype attribute specifies not yet written, but we agreed on syntax in previous discussion, can be a combination of ECMA core datatypes or a classname.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

The scope attribute describes not yet written and can have values instance or static.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<fields>`

fields_element = element fields {
  fields_content  &  fields_attributes  &  foreign_nodes
}
fields_content = (
  descriptive_elements  &  
  field_element*
)
fields_attributes = (
  name?
)

The <fields> element holds zero or more <field> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <fields> element in case multiple <fields> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Globals elements

[edit]

`<globals>`

globals_element = element globals {
  globals_content  &  globals_attributes  &  foreign_nodes
}
globals_content = (
  property_element*  &  properties_element*  &  method_element*  &  methods_element*
)
globals_attributes = (
  getterPattern?  &  setterPattern?  
)

The <globals> element describes not yet written

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Interfaces elements

[edit]

`<interface>`

interface_element = element interface {
  interface_content  &  interface_attributes  &  foreign_nodes
}
interface_content = (
  ancestor_element*  &  ancestors_element*  &  constructor_element*  &  constructors_element*  &  
  exception_element*  &  exceptions_element*  &  mix_element*  &  mixes_element*  &  
  method_element*  &  methods_element*  &  property_element*  &  properties_element*  &  
  descriptive_elements  &  compatibility_elements
)
interface_attributes = (
  name  &  superclass?  &  visibility?  &
  getterPattern?  &  setterPattern?  
)

The <interface> element describes not yet written

The superclass attribute specifies not yet written.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<interfaces>`

interfaces_element = element interfaces {
  interfaces_content  &  interfaces_attributes  &  foreign_nodes
}
interfaces_content = (
  descriptive_elements  &  
  interface_element*
)
interfaces_attributes = (
  name?  &  getterPattern?  &  setterPattern?  
)

The <interfaces> element holds zero or more <interface> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <interfaces> element in case multiple <interfaces> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Method elements

[edit]

`<method>`

method_element = element method {
  method_content  &  method_attributes  &  foreign_nodes
}
method_content = (
  exception_element*  &  exceptions_element*  &  parameter_element*  &  parameters_element*  &  
  returnType_element*  &  returnTypes_element*  &  
  descriptive_elements  &  compatibility_elements
  # Research the above, make consistent with the spec  
)
method_attributes = (
  name  &  scope?  &  visibility?
)

The <method> element describes not yet written

The name attribute describes not yet written.

The scope attribute describes not yet written and can have values instance or static.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<methods>`

methods_element = element methods {
  methods_content  &  methods_attributes  &  foreign_nodes
}
methods_content = (
  descriptive_elements  &  
  method_element*
)
methods_attributes = (
  name?
)

The <methods> element holds zero or more <method> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <methods> element in case multiple <methods> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Mix elements

[edit]

`<mix>`

mix_element = element mix {
  mix_content  &  mix_attributes  &  foreign_nodes
}
mix_content = (
  descriptive_elements
)
mix_attributes = (
  datatype  &  fromScope?  &  toScope?
)

The <mix> element describes not yet written

The datatype attribute describes not yet written, but is a reference to the 'datatype' on the mixin, interface or class that should be mixed in.

The fromScope attribute describes not yet written and can have values instance or static.

The toScope attribute describes not yet written and can have values instance or static.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<mixes>`

mixes_element = element mixes {
  mixes_content  &  mixes_attributes  &  foreign_nodes
}
mixes_content = (
  descriptive_elements  &  
  mix_element*
)
mixes_attributes = (
  name?
)

The <mixes> element holds zero or more <mix> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <mixes> element in case multiple <mixes> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Mixin elements

[edit]

`<mixin>`

mixin_element = element mixin {
  mixin_content  &  mixin_attributes  &  foreign_nodes
}
mixin_content = (
  ancestor_element*  &  ancestors_element*  &  descriptive_elements
)
mixin_attributes = (
  name  &  scope?  &  visibility?
)

The <mixin> element describes not yet written, but defines a collection of methods, properties, etc. that are available to be mixed into other classes (i.e., referred to by a <mix> element)

The name attribute specifies the absolute object name using JavaScript dot notation for the mixin, such as "FooToolkit.io.http" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "http" which is set up as a JavaScript mixin.

The scope attribute describes not yet written and can have values instance or static.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<mixins>`

mixins_element = element mixins {
  mixins_content  &  mixins_attributes  &  foreign_nodes
}
mixins_content = (
  descriptive_elements  &  
  mixin_element*
)
mixins_attributes = (
  name?
)

The <mixins> element holds zero or more <mixin> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <mixins> element in case multiple <mixins> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Namespace elements

[edit]

`<namespace>`

namespace_element = element namespace {
  namespace_content  &  namespace_attributes  &  foreign_nodes
}
namespace_content = (
  descriptive_elements
)
namespace_attributes = (
  name  &  visibility?
)

The <namespace> element can be used to describes a JavaScript object that is a base object for other JavaScript classes but which itself is not a class (i.e., there is no constructor which creates instances of this object). For example, suppose there is a class named "MyLibrary.io.xhr" where the "xhr" object has a constructor, but "MyLibrary" and "io" do not. In this case, "MyLibrary" and "MyLibrary.io" are candidates for the <namespace> element. One way to use the <namespace> element is to provide descriptive information (e.g., using the <description> element) about the base object.

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal". need to document attributes

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<namespaces>`

namespaces_element = element namespaces {
  namespaces_content  &  namespaces_attributes  &  foreign_nodes
}
namespaces_content = (
  descriptive_elements  &  
  namespace_element*
)
namespaces_attributes = (
  name?
)

The <namespaces> element holds zero or more <namespace> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <namespaces> element in case multiple <namespaces> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Parameter elements

[edit]

`<parameter>`

parameter_element = element parameter {
  parameter_content  &  parameter_attributes  &  foreign_nodes
}
parameter_content = (
  option_element*  &  options_element*  &  
  descriptive_elements  &  compatibility_elements
  # Research the above, make consistent with the spec  
)
parameter_attributes = (
  datatype?  &  name  &  usage?  &
  datatype_supplemental_attributes  # FIXME: Is this correct?
)

The <parameter> element describes not yet written

The name attribute specifies not yet written.

The datatype attribute specifies not yet written, but we agreed on syntax in previous discussion, can be a combination of ECMA core datatypes or a classname.

The usage attribute specifies not yet written, but can have the values "required|optional|zero-or-more|one-or-more". 2008-08-16 JON: What is the default? Aptana scriptdoc xml doesn't indicate what the default is.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<parameters>`

parameters_element = element parameters {
  parameters_content  &  parameters_attributes  &  foreign_nodes
}
parameters_content = (
  descriptive_elements  &  
  parameter_element*
)
parameters_attributes = (
  name?
)

The <parameters> element holds zero or more <parameter> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <parameters> element in case multiple <parameters> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Return type elements

2008-09-16 DRAFT CONSENSUS: Change <returns> into <returnType> with plural element <returnTypes>

[edit]

`<returnType>`

returnType_element = element returnType {
  returnType_content  &  returnType_attributes  &  foreign_nodes
}
returnType_content = (
  descriptive_elements
  # Research the above, make consistent with the spec  
)
returnType_attributes = (
  datatype  &  paramName?  &  paramValue?  &
  datatype_supplemental_attributes  # FIXME: Is this correct?
)

The <returnType> element specifies the datatype of the value that the method returns and supplemental descriptive information about the return value.

The datatype attribute specifies the datatype for the value that the method returns. The detailed specification for the datatype attribute can be found in the Datatypes chapter of this specification. However, for the <returns> element, the datatype attribute includes one additional feature that targets factory methods, where the datatype attribute can reference one of the method's parameters. In this case, the string value of the datatype attribute must exactly match the string value of the name attribute on one of the <parameter> elements for this method. If such a match exists between the <returns> element's datatype and the <parameter> element's name, then the return value from the method is the value of that parameter, which can be either a String value (the name of the class) or a Function value (the class constructor). To illustrate, suppose you have the following method definition:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="String"/>
  <returns datatype="classToInstantiate"/>
</method>

The method definition indicates that the return value from the method is an object whose classname is passed as a String to the classFactory method. Now, let's furthermore suppose this method might be invoked at runtime by any of the following:

myShape = classFactory('acme.graphtools.circleClass')
myShape = classFactory('acme.graphtools.rectClass')

In this hypothetical case, the method will return an object that is either an instance of acme.graphtools.circleClass or acme.graphtools.rectClass.

Here is the same example, except that a Function value is used to identify the class:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="Function"/>
  <returns datatype="classToInstantiate"/>
</method>

For this example, the factory method might be invoked as follows (note that the arguments are not quoted, whereas in the previous String example, the class names were in quotes):

myShape = classFactory(acme.graphtools.circleClass)
myShape = classFactory(acme.graphtools.rectClass)

User agents must first look to see if the specified datatype matches one of the parameter names, and then determine if the specified datatype matches one of the ECMAScript core datatypes or the name of a JavaScript class.

The paramName and paramValue attributes are most useful for factory methods where the datatype of the return value is dependent on a parameter whose possible values consists of an enumeration. If paramName and paramValue are provided, then they indicate that when the <parameter> element whose name attribute exactly matches the value of the paramName attribute and where the value of the parameter exactly matches the paramValue attribute, then the method returns the datatype specified on this <returns> element. To illustrate, suppose you have the following method definition:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="String">
    <options>
      <option value="rect"/>
      <option value="circle"/>
    </options>
  </parameter>
  <returns paramName="classToInstantiate" paramValue="rect" datatype="acme.graphtools.rectClass"/>
  <returns paramName="classToInstantiate" paramValue="circle" datatype="acme.graphtools.circleClass"/>
</method>

and furthermore suppose at runtime this method can be invoked by either myShape = classFactory('rect'); or myShape = classFactory('circle');. The above method definition indicates that: (a) when 'rect' is passed as the parameter then the return datatype is 'acme.graphtools.rectClass', and (b) when 'circle' is passed as the parameter then the return datatype is 'acme.graphtools.circleClass'.

Note that paramName and paramValue do not require the use of an enumeration (i.e., <options> and <option> elements). These attributes can also be used on parameters whose datatype is String that do not specify a discrete list of available options.

The metadata file is incorrectly formulated (i.e., in error) for the following situations: (a) if only one of paramName and paramValue are specified; (b) when paramName does not match one of the method's parameters; and (c) when a discrete enumeration is specified and paramValue does not match one of the possible values for the parameter.

Note that attribute datatype is a required attribute in OpenAjax Metadata, whereas in some inline commenting systems such as JSDoc, the datatype might be optional. When converting from these inline commenting systems into OpenAjax Metadata, if the datatype is not specified, a suggested approach is to set datatype to Object.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

`<returnTypes>`

returnTypes_element = element returnTypes {
  returnTypes_content  &  returnTypes_attributes  &  foreign_nodes
}
returnTypes_content = (
  descriptive_elements  &  
  returnType_element*
)
returnTypes_attributes = (
  name?
)

The <returnTypes> element holds zero or more <returnType> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <returnTypes> element in case multiple <returnTypes> are specified.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

[edit]

Subelements defined in other chapters

The following short sections list the subelements of <widget> that are defined in other chapters.

[edit]

`<author>/<authors>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<available>`

Defined in the "Compatibility" chapter.

[edit]

`<deprecated>`

Defined in the " Compatibility" chapter.

[edit]

`descriptive_elements`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<description>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<enum>/<enums>`

Defined in the "Datatypes" chapter.

[edit]

`<example>/<examples>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<include>`

Defined in the "Inclusion" chapter.

[edit]

`<license>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<option>/<options>`

Defined in the "Datatypes" chapter.

[edit]

`<property>/<properties>`

Defined in the "Properties" chapter.

[edit]

`<reference>/<references>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<remarks>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<title>`

Defined in the "Descriptive elements and attributes" chapter.

[edit]

`<topic>/<topics>`

Defined in the "Topics" chapter.

[edit]

`<useragent>/<useragents>`

Defined in the " Compatibility" chapter.

EDITOR: Make sure that all 'datatype' attributes refer to datatypes chapter and make sure there is appropriate writeup on classname datatypes to talk about the use of JavaScript dot notation to identify classes.

[edit]

Recently closed items

We are waiting on Bertrand to make a proposal about distinguishing between properties and fields.
Waiting on proposal from Bertand about the whole area of enumerated values, including how to deal with flags.
Waiting on proposal from Ingo on mixins.
Probably should hyperlink-reference a shared <property> definition within the Properties and Datatypes chapter. We need to document the differences in attribute lists for <property> when used within a class definition and <property> when used within a widget description. At 2008-04-10 telecon, we decided it was better to have duplicate descriptions of the two different <property> elements.
We comparison matrix says the following: "2008-03-06 DRAFT CONSENSUS: Spec needs to mention relationship to namespaces. What does the previous blue sentence mean?". Is there something that still needs to be done regarding namespaces? At 2008-04-10 telecon, no one could remember what this was about, so we will ignore it for now, and assume if there is a problem, we will notice it later.
Need to come up with appropriate words to talk about the use of HTML markup within descriptions and remarks. Here is what Jon said in his email: "As a result, unless someone finds something more suitable, we are probably going to have to simply say: (a) the content needs to restrict itself to HTML content that is allowed within a DIV, which means the content SHOULD NOT use BASE, BODY, IFRAME, FRAME, FRAMESET, HEAD, HTML, or TITLE, (b) the developer need to understand that in some scenarios the tool might not have a full browser engine capable of rendering arbitrary HTML, so he might want to use a simple subset of HTML, (c) the developer SHOULD avoid inclusion of any scripting (e.g., <script>, onclick/onmouseover/etc, javascript: protocol). Furthermore, tool vendors that might use a browser engine to render the content might consider using a whitelist approach to any HTML content where only a well-known set of tags and attributes are allowed." Here is the text from our draft consensus: "can take HTML, if it breaks XML must wrap in CDATA, tool makes best effort to render, content is snippet that goes into an implicit DIV, burden on author to use a portable subset, will recommend and provide pointer to a portable subset " At 2008-04-10 telecon, we decided the following:
- Burden on author to use HTML that is portable
- Suggest to authors that XHTML is likely to be more portable
- Suggest to authors that a simple subset of HTML (DIV, P, SPAN, lists) is likely to be more portable
- Suggest to authors to avoid JavaScript in the content
- Should be suitable for inclusion within an HTML DIV
- No restrictions on the markup that might be used
- We would recommend that tools use a whitelist approach for security reasons, especially to eliminate any scriptable content
- Recommend well-formed HTML, but if not well-formed, MUST be bracketed in CDATA
- Tools should be aware that some of the content may not be well-formed and may be wrapped in CDATA
- Authors should be aware that some tools might only use the text content and therefore ignore any markup (elements and attributes)
Might want to use the 'datatype' attribute only for cases when we are talking about datatypes, and use a different attribute name for other cases. At 2008-04-10 telecon, we made sure that 'datatype' attribute was only used for cases where we are talking about datatypes
For the cases where the 'datatype' attribute is about datatypes, we probably should simply hyperlink-reference the description within the Properties and Datatypes chapter At 2008-04-10 telecon, we agreed to try the approach where this chapter's 'datatype' attribute references the datatypes chapter
Do we have enough consistency regarding overloading? We decided to allow multiple constructors and multiple definitions of the same method name. Should we also allow multiple definitions of a parameter and a return datatype? At 2008-04-10 telecon, we decided that we didn't need to allow redundant definitions (i.e., overloading) of parameters and return datatypes. If things are so complex that redundant makes sense, then the developer can define a redundant constructor or method.

Retrieved from "http://www.openajaxalliance.org/member/wiki/OpenAjax_Metadata_Specification_API_Metadata"

OpenAjax Metadata Specification API Metadata

From MemberWiki

Contents

3 API Metadata

Introduction

Feature overview

Example

API metadata

The <api> element

Subelements defined in this chapter

Alias elements

<alias>

<aliases>

Ancestor elements

<ancestor>

<ancestors>

Class elements

<class>

<classes>

Constructor elements

<constructor>

<constructors>

Event elements

<event>

<events>

Exception elements

<exception>

<exceptions>

Field elements

<field>

<fields>

Globals elements

<globals>

Interfaces elements

<interface>

<interfaces>

Method elements

<method>

<methods>

Mix elements

<mix>

<mixes>

Mixin elements

<mixin>

<mixins>

Namespace elements

<namespace>

<namespaces>

Parameter elements

<parameter>

<parameters>

Return type elements

<returnType>

<returnTypes>

Subelements defined in other chapters

<author>/<authors>

<available>

<deprecated>

descriptive_elements

<description>

<enum>/<enums>

<example>/<examples>

<include>

<license>

<option>/<options>

<property>/<properties>

<reference>/<references>

<remarks>

<title>

<topic>/<topics>

<useragent>/<useragents>

Recently closed items

Views

Personal tools

Navigation

Search

Toolbox

The `<api>` element

`<alias>`

`<aliases>`

`<ancestor>`

`<ancestors>`

`<class>`

`<classes>`

`<constructor>`

`<constructors>`

`<event>`

`<events>`

`<exception>`

`<exceptions>`

`<field>`

`<fields>`

`<globals>`

`<interface>`

`<interfaces>`

`<method>`

`<methods>`

`<mix>`

`<mixes>`

`<mixin>`

`<mixins>`

`<namespace>`

`<namespaces>`

`<parameter>`

`<parameters>`

`<returnType>`

`<returnTypes>`

`<author>/<authors>`

`<available>`

`<deprecated>`

`descriptive_elements`

`<description>`

`<enum>/<enums>`

`<example>/<examples>`

`<include>`

`<license>`

`<option>/<options>`

`<property>/<properties>`

`<reference>/<references>`

`<remarks>`

`<title>`

`<topic>/<topics>`

`<useragent>/<useragents>`