JavaScript API Comparison Matrix
From MemberWiki
This wiki page shows a comparison matrix between the following existing industry technologies that are used to document JavaScript APIs:
- Aptana's ScriptDoc XML format and Aptana's @whatever doc comment syntax
- JSDoc version 2
- Microsoft's doc comment format
Comparison matrix
| Aptana | JSDocV2 | Microsoft | Comments/decision | How this might map to inline doc comments |
|---|---|---|---|---|
| <aliases>, <alias name="" type="">, @alias | ? | - | 2008-02-28 DRAFT CONSENSUS: Support aliases and alias. 2008-03-06 DRAFT CONSENSUS: <alias> will have a 'name' attribute. 2008-04-08 DRAFT CONSENSUS: After Ingo investigated, we concluded that we don't need 'type', just 'name'. (Aptana uses the 'type' attribute mainly to address browser HTML issues.) | ? |
| - | @augments objname, @extends objname | Not sure if this is just mix-ins or if it's inheritance. Not in doc comments |
(JSDocsV2) all the properties and methods of the objname are attached to this. 2008-03-06 DRAFT CONSENSUS: Don't support @augments in our XML grammar. 2008-03-11 DRAFT CONSENSUS: <class> will have child elements <ancestors> and <mixedins>. <ancestors> will have <ancestor> child elements. <mixedins> will have <mixed> child elements with a scope="instance|static" attribute. Ingo needs to submit a revised proposal about mixins.</span</td>
| ?</td>
</tr> |
| @author</td> | -</td> | ?</td> | 2008-02-28 DRAFT CONSENSUS: Will have <authors> with can have any number of <author> children. We assume the content of <author> can be any string which might include email or web site info.</td> | ?</td>
</tr> |
| <availability></td> | ?</td> | ?</td> | 2008-02-28 DRAFT CONSENSUS: Do not support 'availability'. 2008-03-06 DRAFT CONSENSUS: Spec needs to mention relationship to namespaces. What does the previous blue sentence mean? 2008-04-08 DRAFT CONSENSUS: Aptana's <availability>/<specification> is mainly for documenting HTML elements by browser. Won't be in our spec. Assumption is Aptana will use namespace extensions for this feature. </td> | ?</td>
</tr> |
| <browsers>, <browser></td> | ?</td> | -</td> | 2008-02-28 DRAFT CONSENSUS: Support ability to identify browsers, but use a tagname such as <useragents> given how the Web Runtime is being used increasingly outside of the browser. 2008-04-08 DRAFT CONSENSUS: After Ingo investigated, he felt that Aptana's approach was good. We decided to put attributes 'platform' (e.g., "IE","Mozilla",etc), 'version' (version#), 'os' (e.g., "Windows"), and 'osversion' (version#), where only 'platform' is required. Further, we agreed on syntax for version#s, either NUMBER+ or -NUMBER or NUMBER-NUMBER, such as "3.0+" (which means 3.0 or more), "-4.0" (which means up to and including 4.0), and "3.0-4.0" (range).</td> | ?</td>
</tr> |
| <class type="" superclass="" visibility=""></td> | -</td> | Not in doc comments In metadata:
<api id="T:J#Sys.UI.Control"><family><ancestors><type api="T:J#Sys.Component"/></ancestors></family></api> | 2008-02-28 DRAFT CONSENSUS: Support 'class', but also support a sibling element <globals> for APIs that are not part of a class 2008-03-06 DRAFT CONSENSUS: Reconfirm support of 'class'and <globals>, also talked about siblings <interface> and <mixin> 2008-03-06 DRAFT CONSENSUS: Agree to 'ancestor' on <class> which can hold a space-separated list of XML IDs, which are IDs (using 'id' attribute) that are assumed to be unique across a toolkit's metadata files, not just unique within a single XML file. 2008-03-06 DRAFT CONSENSUS: Agree to 'name' on <class> and also 'visibility' with values 'public', 'private', 'protected', 'internal', and 'protected-internal'. 2008-03-11 DRAFT CONSENSUS: Get rid of 'ancestor' attribute on <class> and have <ancestors> and <mixedins> subelements. Ingo needs to send email about possible changes to mixins after exploring Dojo's use of this feature. Still need to talk about 'type'. </td> | ?</td>
</tr> |
| @classDescription</td> | @class description, @namespace...</td> | In doc comments, type and contructor are the same entity. In metadata, the constructor is separate from the class. For example, <api id="T:J#Sys.UI.Control.#ctor"></td> | (JSDocsV2) used with a constructor to provide a description of the class separate from the constructor's description. used with an object literal to treat the object as a class. 2008-03-06 DRAFT CONSENSUS: @classDescription maps to <description>, child of <class>. Also confirmed that <description> is available as a child of lots of things, particular some of the descendants of <class></td> | ?</td>
</tr> |
| -</td> | @config {type} propertyname description</td> | In doc comments, <param name="foo" optional="true"/></td> | (JSDocsV2) used to document a required property of a parameter. if it follows a parameter then it is assumed to apply to that parameter. 2008-03-06 DRAFT CONSENSUS: Don't include a special XML construct just for @config. Similar to attribute on a class. Try to map @config into our XML for classes. If classes can be mapped back into @ syntax, probably would map to different @ construct that @config.</td> | ?</td>
</tr> |
| -</td> | ?</td> | Global namespace is empty namespace, i.e. <api id="N:J#"><apidata group="namespace" name="Global"/></api>. Functions directly under the global namespace not supported.</td> | 2008-02-28 DRAFT CONSENSUS: Support 'class', but also support a sibling element <globals> for APIs that are not part of a class</td> | ?</td>
</tr> |
| <constructors>, <constructors scope="" mode="" visibility="">, @constructor</td> | @constructor</td> | In doc comments, type and contructor are the same entity. In metadata, the constructor is separate from the class. For example, <api id="M:J#Sys.UI.Control.#ctor"></td> | (JSDocsV2) mark this function as a constructor. 2008-03-25 DRAFT CONSENSUS: <methods>/<method constructor="true|false" visibility="..."> 2008-04-01 DRAFT CONSENSUS: We changed our minds. Now, we are going with <constructors>/<constructors visibility="...">. Furthermore, we decided that the markup can define the constructor, or any method, multiple times, which has the effect of defining different signatures for the same method. We also talked about 'advanced'. Aptana has this as a possible value for 'visibility', but we decided to not support 'advanced' within our format. Aptana can define an extension using namespacing if it wants.</td> | ?</td>
</tr> |
| <deprecated>, @deprecated</td> | @deprecated description</td> | ?</td> | (JSDocV2) used to provide information about a deprecation of a class, method or object. 2008-03-25 DRAFT CONSENSUS: <deprecated> where child content is just text 2008-04-08 DRAFT CONSENSUS: Will have <deprecated [version="..."]>...optional text</deprecated>. Companion to <available [version="..."]>.</td> | ?</td>
</tr> |
| <description></td> | @description, @desc</td> | <summary> in doc comments. In metadata, a separate file contains the descriptions and point to the apis using their ids.</td> | (JSDocV2) a description of this (synonym desc). this is an alternative to including an untagged description before any tags. 2008-03-25 DRAFT CONSENSUS: <description> 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 ACTION: Jon to research where a portable subset of HTML is defined such that we can reference it</td> | ?</td>
</tr> |
| -</td> | @event</td> | <summary> tag in an event adder for doc-comments.
In metadata, <api id="E:J#Sys.INotifyPropertyChange.propertyChanged"> <apidata group="member" subgroup="event" name="propertyChanged" /> [...] <eventdata add="true" remove="true" /> <eventhandler> <type api="T:J#Function" /> </eventhandler> </api> </td> | (JSDocV2) mark this method as an event on the containing class. 2008-04-03 DRAFT CONSENSUS: <class>/<events>/<event>/<parameters>/<parameter> (for proprietary event systems within each toolkit) and <topics>/<topic> (for OpenAjax Hub events). <topics> can be a child of <widget> or <class>. Also, <eventHandlersPatterns</{<addEventHandlerPattern>,<removeEventHandlerPattern>} where these elements are a child of <library> and identify pattern naming conventions for the add/remove subscriber methods, such as '{token} = OpenAjax.hub.subscribe({name}, {handler})'. Probably want shorter tagnames and may want an alternative syntax to make it easier for IDEs to recognize add/remove subscriber methods.</td> | ?</td>
</tr> |
| <example></td> | @example examplecode</td> | <example> in doc comments.</td> | (JSDocV2) an example of how to use the function or object. (Aptana) a snippet of HTML 2008-03-25 DRAFT CONSENSUS: <examples>/<example>. Can take HTML like <description>. (See above)</td> | ?</td>
</tr> |
| <exceptions>, <exception type="">, @exception</td> | @exception {type} description, @throws...</td> | We have always had a more relaxed way of describing exceptions, usually in the text of the description (there is no mandatory exception declaration in .NET)</td> | (JSDocV2) explain an error a function can throw (synonym throws). 2008-04-01 DRAFT CONSENSUS: Will support <exceptions>/<exception type="..."> 2008-04-01 DRAFT CONSENSUS: 'type' can take either a built-in ECMA type or a classname</td> | ?</td>
</tr> |
| -</td> | @fileOverview description</td> | -</td> | (JSDocV2) describe the entire file. 2008-04-01 DRAFT CONSENSUS: Add <description> as a child element to <api></td> | ?</td>
</tr> |
| -</td> | @function</td> | -</td> | (JSDocV2) force the object to be treated as a function. 2008-04-01 DRAFT CONSENSUS: We think we have this covered due to <globals> which can has methods within it.</td> | ?</td>
</tr> |
| @id</td> | -</td> | id in metadata</td> | 2008-04-01 DRAFT CONSENSUS: We don't think we need to worry about this in the XML markup as this is only a JSDoc-to-JSDoc referencing feature which would be flattened away in the conversion into XML.</td> | ?</td>
</tr> |
| -</td> | @ignore</td> | -</td> | (JSDocV2) never show this in the documentation. 2008-04-01 DRAFT CONSENSUS: We don't think we need to worry about this in the XML markup as this is only an indicator to JavaScript parsers that the following method or property should not be parsed when building API documentation.</td> | ?</td>
</tr> |
| @inherits</td> | @inherits objname</td> | In metadata:
<api id="T:J#Sys.UI.Control"><family><ancestors><type api="T:J#Sys.Component"/></ancestors></family></api></td> | (JSDocV2) that objname is a property or method attached to this. 2008-04-01 DRAFT CONSENSUS: We have tentatively concluded that we have this covered due to our <ancestor> element Need to review this once again when we see Ingo's mixin proposal.</td> | ?</td>
</tr> |
| <interfaces>, <interface type=""></td> | ?</td> | <api id="T:J#Sys.IDisposable"><apidata group="type" subgroup="interface" name="IDisposable"/>/</td> | 2008-04-03 DRAFT CONSENSUS: Yes, we will have <interfaces>, <interface type=""> as a sibling to <class>. Assume same children and attributes and <class> but some attributes and attribute values may not make sense and will need to be documented as such.</td> | ?</td>
</tr> |
| <javascript></td> | ?</td> | <reflection><apis></td> | 2008-02-28 DRAFT CONSENSUS: Root element will be <api> instead of <javascript></td> | ?</td>
</tr> |
| @memberOf</td> | @memberOf objname</td> | In metadata:
<containers> <library assembly="" module="MicrosoftAjax"/> <namespace api="N:J#Sys.UI"/> <type api="T:J#Sys.UI.DomElement"/> </containers> </td> | (JSDocV2) this function or object is a method or property of objname. 2008-04-03 DRAFT CONSENSUS: We don't need extra XML for this. Transcoder from JSDoc (or whatever) into XML will transcode this into a class method or class field/property</td> | ?</td>
</tr> |
| <methods>, <method name="" scope=""></td> | ?</td> | In metadata:
elements/element under api gives the list of members. These members specify their container type in their own description. </td> | 2008-04-03 DRAFT CONSENSUS: Yes, we will have <methods>, <method name="" scope=""> .</td> | ?</td>
</tr> |
| -</td> | @name objname</td> | ?</td> | (JSDocV2) use the given name to document the object, and ignore whatever is in the code that follows. 2008-04-03 DRAFT CONSENSUS: We don't need extra XML for this. Transcoder from JSDoc (or whatever) into XML will transcode/flatten this</td> | ?</td>
</tr> |
| @namespace</td> | @namespace (see @class above)</td> | <api id="N:J#Sys.UI"><apidata group="namespace" name="UI"/></td> | 2008-04-03 DRAFT CONSENSUS: We don't need extra XML for this. Transcoder from JSDoc (or whatever) into XML will transcode/flatten this</td> | ?</td>
</tr> |
| <parameters>, <parameter>, @param</td> | @param {type} name description, with [name] for optional params</td> | In doc comments: <param name="parameterName"
mayBeNull="true|false" optional="true|false" type="ParameterType" parameterArray="true|false" integer="true|false" domElement="true|false" elementType="ArrayElementType" elementInteger="true|false" elementDomElement="true|false" elementMayBeNull="true|false">Description</param> In metadata: <parameters> <parameter name="ignoreCase"><type api="T:J#Boolean"/> </td> | 2008-04-01 DRAFT CONSENSUS: 'type' can take either a built-in ECMA type or a classname 2008-04-03 DRAFT CONSENSUS: Yes, we will have <parameters>, <parameter name="" type="" usage="required|optional|zero-or-more|one-or-more"> .</td> | ?</td>
</tr> |
| -</td> | @private</td> | In metadata: <memberdata visibility="private"/> but we don't document private members.</td> | (JSDocV2) will be excluded from the documentation without the -p option. 2008-04-03 DRAFT CONSENSUS: Already addressed by 'private' value on 'visibility' attribute.</td> | ?</td>
</tr> |
| @projectDescription</td> | -</td> | ?</td> | 2008-04-03 DRAFT CONSENSUS: Already addressed by <description>.</td> | ?</td>
</tr> |
| <properties>, <property>, @property</td> | @property {type} name description</td> | In metadata:
<apidata group="member" subgroup="field|property" name="x"/> </td> | 2008-02-?? TENTATIVE RESOLUTION: Support properties and property, due to earlier long discussion about properties and datatypes We probably will need to document which attributes only make sense for widgets. ACTION Bertrand to draft a proposal about distinguishing between properties and fields.</td> | ?</td>
</tr> |
| <references>, <reference name=""></td> | ?</td> | ?</td> | 2008-04-03 DRAFT CONSENSUS: We will have one or both of <see> and <seealso>. Waiting on proposal from Bertrand about which one(s) we need and any parent/child relationships between the proposed tags ACTION Bertrand to draft a proposal.</td> | ?</td>
</tr> |
| <remarks></td> | ?</td> | <remarks></td> | (Aptana) snippet of HTML 2008-04-08 DRAFT CONSENSUS: We will have <description>, <remarks>, and <examples>, all peers, all available wherever <description> can go. All are optional for authors, and tools may or might not display the information.</td> | ?</td>
</tr> |
| <return-description>, @return</td> | ?</td> | Text of the returns tag in doc comments.</td> | 2008-04-08 DRAFT CONSENSUS: Maps to <description> as a child of <returns>.</td> | ?</td>
</tr> |
| <return-types>, <return-type></td> | @return {type} description</td> | In doc comments: <returns type="String"/>
In metadata: <returns><type api="T:J#String"/></returns> </td> | 2008-02-28 DRAFT CONSENSUS: Support a single <returns type="...">, not multiple return-types, where 'type' works like <property> element and can take a list 2008-04-01 DRAFT CONSENSUS: 'type' can take either a built-in ECMA type or a classname</td> | ?</td>
</tr> |
| -</td> | @scope objname, @scope objname.prototype</td> | In doc comments, it's contextual. In metadata, <memberdata static="true"/></td> | (JSDocV2) the next object literal's properties/methods are attached to either objname or objname prototype 2008-04-08 DRAFT CONSENSUS: We don't need extra XML for this. Transcoder from JSDoc (or whatever) into XML will transcode/flatten this</td> | ?</td>
</tr> |
| @sdoc</td> | -</td> | ?</td> | JSDoc indicator for when an external file contains the documentation (versus being inline) 2008-04-08 DRAFT CONSENSUS: We don't need extra XML for this. Transcoder from JSDoc (or whatever) into XML will transcode/flatten this</td> | ?</td>
</tr> |
| @see</td> | -</td> | <see> <seealso></td> | 2008-04-08 DRAFT CONSENSUS: Maps to either <see> or <seealso>. See <references> row above for more.</td> | ?</td>
</tr> |
| @since</td> | -</td> | Versioning is done for the whole file, not for individual apis.</td> | 2008-04-08 DRAFT CONSENSUS: Will have <available [version="..."]>...optional text</available>. Companion to <deprecated [version="..."]>.</td> | ?</td>
</tr> |
| <specification></td> | ?</td> | -</td> | 2008-04-08 DRAFT CONSENSUS: Aptana's <availability>/<specification> is mainly for documenting HTML elements by browser. Won't be in our spec. Assumption is Aptana will use namespace extensions for this feature.</td> | ?</td>
</tr> |
| -</td> | @static</td> | -</td> | (JSDocV2) used with a class to declare the class has no constructor. 2008-04-08 DRAFT CONSENSUS: We don't need extra XML for this. We already have mechanisms defined for capturing 'static'.</td> | ?</td>
</tr> |
| @type</td> | @type whattype</td> | In metadata:
<api id="T:J#Sys.Component"> <apidata group="type" subgroup="class" name="Component"> <typedata visibility="public"/> for type definitions. Types of parameters, properties, fields and return values are specified through the type attribute in doc comments and through the api attribute in metadata. </td> | 2008-04-08 DRAFT CONSENSUS: We already resolved the 'type' attribute after previous long discussion.</td> | ?</td>
</tr> |
| <values>, <value></td> | ?</td> | In doc comments, enumeration members are described as fields (in the enum constructor).
In metadata, the enumeration itself is of group "type" and subgroup "enumeration". The members are of group "member" and subgroup "field". They are also marked as static in memberdata. </td> | (Aptana) apparently for enums 2008-04-08 DRAFT CONSENSUS: We resolved that we will describe enumerations but haven't agreed on semantics or syntax. However, we are actively considering that Aptana's markup: 7lt;parameter>/<values>/<value>. Need to resolve various issues, such as exact markup and what do to about "flags". Bertrand has action to make a proposal. </td> | ?</td>
</tr> |
| @version</td> | ?</td> | The whole file is versioned, but version information is not embedded in the file.</td> | 2008-04-08 DRAFT CONSENSUS: There will be a 'version' attribute on the <api> element.</td> | ?</td>
</tr> </table> |
