OpenAjax Metadata 1.0 Specification API Metadata Overview
From MemberWiki
NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.
Contents |
Chapter 5: API Metadata Overview
Introduction
This chapter provides an overview of "OpenAjax API Metadata".
The OpenAjax API Metadata provides a standard XML syntax for defining JavaScript APIs found in JavaScript files and Ajax/JavaScript libraries.
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:
Feature overview
OpenAjax Metadata defines standard XML metadata that describes the runtime JavaScript APIs (classes, methods, properties) that are available within a particular JavaScript file or an Ajax/JavaScript library. The key features within the XML metadata include:
- <api>
- The <api> element is the root element of an API metadata file. Child elements can include <class>, <interface>, <singleton>, <mixin>, <namespace>, <globals>, <config>, and <enum>.
- <class>
- A class is a collection of related JavaScript logic that allows for object instantiation via the 'new' operator. Child elements can include <ancestor>, <constructor>, <method>, <property>, <mix>, <alias>, <config>, and <event>.
- <interface>
- An interface is a logical group of methods and properties that are used as a superclass by other classes or interfaces. Typically, <interface> elements are referenced by <ancestor> elements. Child elements are similar to those available on the <class> element.
- <singleton>
- A singleton is a global static JavaScript object that functions like a <class> in that it might include its own methods and properties, but unlike <class>, does not include the ability to construct new instances of itself. Child elements are similar to those available on the <class> element.
- <mixin>
- A mixin defines a collection of methods and properties that are available to be mixed into other classes (i.e., referred to by a <mix> element). Child elements are similar to those available on the <class> element.
- <namespace>
- A namespace 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 that creates instances of this object).
- <globals>
- The <globals> element describes properties and methods that are global to the JavaScript runtime environment (i.e., available directly from the JavaScript window object) and therefore not contained inside a particular namespace or class.
- <config>
- The <config> element is a grouping element that provides a detailed definition for a JavaScript object that can be referred to by a datatype attribute. The <config> element lists the properties (via child <property> elements) that can exist on that object. A primary use case for the <config> element is to describe an object that can be used as a parameter to a <method> or a <constructor>.
- <enum>
- An <enum> element defines a reusable enumeration that can be referenced from a 'datatype' attribute.
Example
Here is an example of some of the constructs in OpenAjax Metadata for documenting JavaScript APIs:
<?xml version="1.0" encoding="UTF-8"?> <api xmlns="http://openajax.org/metadata" version='1.0' spec='1.0'> <class name="libraryname.ClassName"> <ancestor datatype="Object"/> <constructor> <description>Constructor description</description> <parameter name="message" usage="required" datatype="String"> <description>Parameter description</description> </parameter> <returnType datatype="Object"> <description>Return type description</description> </returnType> </constructor> <property name="propertyInstance" scope="instance" datatype="String" defaultValue=""> <description>Property description</description> </property> <property name="propertyStatic" scope="static" datatype="String" defaultValue=""> <description>Property description</description> </property> <method name="functionInstance" scope="instance"> <description>Method description</description> <parameter name="param" usage="required" datatype="String"> <description>Parameter description</description> </parameter> <returnType datatype="String"> <description>Return type description</description> </returnType> </method> <method name="functionStatic" scope="static"> <description>Method description</description> <returnType datatype="String"> <description>Return type description</description> </returnType> </method> </class> </api>
Detailed API definitions
The following chapter:
is the starting point for detailed definitions of the XML metadata to describe JavaScript APIs. Subsequent chapters contain supplemental specification details on selected topics:
- Descriptive elements and attributes
- Compatibility elements and attributes
- Properties
- Datatypes
- Localization
- Variable Substitution
- Plural and Singular Elements