OpenAjax Metadata 1.0 Specification API Metadata Overview

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.

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


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:

Image:OAMConverter.png

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:


<--previous       contents--^       next-->
Retrieved from "/member/wiki/OpenAjax_Metadata_1.0_Specification_API_Metadata_Overview"
Personal tools