widlproc

Tim Renouf, Aplix Corp

$Id$

Introduction

widlproc is a processor that accepts as input Web IDL (the 30 September 2009 editor's draft), with comments in a subset of the format used by Doxygen. The format it accepts is proposed by Aplix for authoring BONDI interface definitions.

The output of widlproc is an XML representation of the Web IDL input, with added XML elements representing the Doxygen-like comments.

Usage

widlproc filename

widlproc reads the file named filename, and sends its XML output format to stdout.

Input format

The input format accepted by widlproc is Web IDL (with an extension used in the W3C Geolocation API), with comments in a format reminiscent of that used by Doxygen.

Web IDL extension from W3C geolocation API

double

double is allowed as a DeclarationType or a BoxedType.

Doxygen-like comment introduction

Only a small subset of Doxygen functionality is supported by widlproc, plus additions to handle the BONDI concepts of API features and device capabilities.

In particular, no links are added automatically. (This could be added in the future.)

Doxygen comment block

Comment referral point

Each Doxygen comment block refers to a comment referral point in the Web IDL, one of module, interface, exception, const, attribute, operation or argument.

Block comment

A block comment (delimited by /* */) whose first character after the /* is ! or a second * is a Doxygen comment block.

Normally the comment block refers to the next comment referral point in the Web IDL. If the first character is <, so the comment block is introduced with /**< or /*!< , then the comment block refers back to the previous comment referral point.

The text of the comment block excludes the initial ! or * (and the < for a referring back block), and excludes an initial (after whitespace) * on each line, and, when not in a \code block, excludes any line consisting entirely of whitespace, then * characters, then whitespace.

widlproc does not support Doxygen commands to force a comment block to refer to a different referral point.

Inline comments

The maximal sequence of inline comments (delimited by //) on adjacent lines, where all of the following conditions hold:

each has a first character after the / of ! or a third /;
no comment referral point intervenes;
either each comment in the sequence starts with a < (see below), or none does;
the sequence contains at least two inline comments, or, if only one, then it starts with < (see below);

forms a Doxygen comment block.

Normally the comment block refers to the next comment referral point in the Web IDL. If the first character of each comment is <, so each comment in the block is introduced with ///< or //!< , then the comment block refers back to the previous comment referral point.

The text of the comment block excludes the initial ! or / (and the < for a referring back block) of each inline comment, and, when not in a \code block, excludes any line consisting entirely of whitespace, then / characters, then whitespace.

widlproc does not support Doxygen commands to force a comment block to refer to a different referral point.

Paragraph

A comment block is broken into zero or more paragraphs. One or more blank lines break the paragraphs (unless in a \code block).

Certain commands (below) also start a new paragraph.

An HTML block element is a paragraph. A blank line (other than in a \code block) implicitly closes any open HTML elements, thus ending the paragraph.

Doxygen-like commands

widlproc supports a small subset of Doxygen commands, plus some additions to handle BONDI API features and device capabilities.

A command is always introduced with a \ character. The Doxygen alternative (from JavaDoc) of @ is not supported.

\api-feature

Starts a new paragraph. The following word is the name of an API feature used by the method being documented. The remainder of the paragraph is any description required of how (eg in what circumstance) the API feature is used.

\author

Starts a new paragraph. The remainder of the paragraph contains information about a single author of the specification. Multiple \author commands should be used for multiple authors.

(Here widlproc differs from Doxygen; Doxygen also allows multiple authors on separate lines to appear in one \author paragraph.)

\b

This renders the next word as bold. It is equivalent to enclosing the next word with <b> </b>.

\brief

Starts a new paragraph. The remainder of the paragraph contains a brief description of the entity being documented.

\code, \endcode

\code starts a new paragraph which is a code block. The code block ends at the next \endcode command.

Within the code block, whitespace and newlines are passed verbatim into the output.

\def-api-feature

Starts a new paragraph. The following word is the name of the API feature which is defined here. The description is an def-api-feature block, consisting of the remainder of the paragraph, together with further paragraphs in the same block comment each of which is a plain paragraph, a paragraph started due to HTML markup, a \brief paragraph, or a \device-cap paragraph.

\def-api-feature-set

Starts a new paragraph. The following word is the name of the API feature set which is defined here. The description is an def-api-feature-set block, consisting of the remainder of the paragraph, together with further paragraphs in the same block comment each of which is a plain paragraph, a paragraph started due to HTML markup, a \brief paragraph, or a \api-feature paragraph.

\def-device-cap

Starts a new paragraph. The following word is the name of the device capability which is defined here. The description consists of the remainder of the paragraph, together with further paragraphs in the same block comment each of which is a plain paragraph, a paragraph started due to HTML markup, a \brief paragraph, or a \param paragraph.

\def-instantiated

Starts a new paragraph. The description is an def-instantiated block, consisting of the remainder of the paragraph, together with further paragraphs in the same block comment each of which is a plain paragraph, a paragraph started due to HTML markup, a \brief paragraph, or a \api-feature paragraph.

\device-cap

Starts a new paragraph. This command can appear only inside an def-api-feature block. The following word is the name of a device capability used by the API feature being documented. The remainder of the paragraph is any description required of how (eg in what circumstance) the device capability is used.

\n

Creates a line break in the output.

\param

Starts a new paragraph. This takes the following word as the name of a parameter (argument) of the entity being documented, then makes the remainder of the paragraph refer to that parameter.

\return

Starts a new paragraph. The remainder of the paragraph is made to refer to the return type of the entity being documented.

\throw

Starts a new paragraph. The next word is taken to be the name of an exception thrown by the entity being documented, and the remainder of the paragraph documents that exception (in the raises list of an operation, or the setraises clause of an attribute).

\version

Starts a new paragraph. The remainder of the paragraph contains version number information.

Escape sequences

The following escape sequences are recognized in a comment block:

escape sequence	result
`\\`	`\`
`\&`	`&` (escaped to `&` in output XML)
`\$`	`$`
`\#`	`#`
`\<`	`<` (escaped to `<` in output XML)
`\>`	`>`
`\%`	`%`

Some of these escape sequences are used to avoid Doxygen features that widlproc does not currently implement. In particular, widlproc insists on a $ being escaped, to allow for possible future functionality.

HTML in comments

widlproc accepts a small subset of HTML elements.

An HTML block element is a paragraph. A blank line (other than in a \code block) implicitly closes any open HTML elements, thus ending the paragraph.

The following HTML block elements are accepted: dl p table ul

The following HTML inline elements are accepted: b br em

The following HTML elements are accepted where valid inside one of the other elements: dd dt li td th tr

Output format

The output of widlproc is an XML representation of the Web IDL, with added XML elements representing the Doxygen-like comments.

Annotated document type declaration

<!-- Autogenerated from widlproc.html : do not edit. -->

Entities used elsewhere

<!ENTITY % block 'dl | p | table | ul' >
<!ENTITY % Block '(%block;)*' >
<!ENTITY % inline 'a | b | br | em' >
<!ENTITY % Inline '(#PCDATA | %inline;)*' >
<!ENTITY % Flow '(#PCDATA | %inline; | %block;)*' >

<!ELEMENT webidl (#PCDATA | ref)* >

The <webidl> element contains the literal text of the original Web IDL that the parent element was parsed from, minus the comments, with each reference to an interface name enclosed in a <ref>..</ref>.

Definitions

Definitions is the root element of the XML document.

The ExtendedAttributeList specifies any extended attributes for the Module, Interface, Exception, Typedef, Valuetype or Const in the Definition.

<!ELEMENT Definitions (Module | Interface
    | Exception | Typedef | Implements)* >

Module

A Module represents an API. The name attribute specifies the name of the API. The descriptive element provides its documentation if any. The id attribute specifies the absolute scoped name of the module.

<!ELEMENT Module (webidl, descriptive?, ExtendedAttributeList?,
        (Module | Interface | Exception | Typedef | Implements)* ) >
<!ATTLIST Module name CDATA #REQUIRED 
                 id CDATA #REQUIRED >

Interface

An Interface represents an interface. The name attribute specifies the name of the interface. The descriptive element provides its documentation if any. The id attribute specifies the absolute scoped name of the interface.

The InterfaceInheritance element indicates that the interface inherits from other interface(s). Each Name in the InterfaceInheritance has a name attribute giving the scoped name of the interface being inherited from.

<!ELEMENT Interface (webidl, descriptive?, ExtendedAttributeList?,
        InterfaceInheritance?, (Const | Stringifier | Attribute | Operation)* ) >
<!ATTLIST Interface name CDATA #REQUIRED
                    id CDATA #REQUIRED >

<!ELEMENT InterfaceInheritance (Name+) >

<!ELEMENT Name EMPTY >
<!ATTLIST Name name CDATA #REQUIRED >

Exception

An Exception represents an exception. The name attribute specifies the name of the exception. The descriptive element provides its documentation if any. The id attribute specifies the absolute scoped name of the exception.

An ExceptionField represents a field in an exception. The name attribute specifies the name of the field. The Type element specifies its type. The descriptive> element provides its documentation if any. The id attribute specifies the absolute scoped name of the field.

<!ELEMENT Exception (webidl, descriptive?, ExtendedAttributeList?,
        (Const | ExceptionField)* ) >
<!ATTLIST Exception name CDATA #REQUIRED 
                    id CDATA #REQUIRED >

<!ELEMENT ExceptionField (descriptive?, ExtendedAttributeList?, Type) >
<!ATTLIST ExceptionField name CDATA #REQUIRED
                         id CDATA #REQUIRED >

Typedef

A Typedef represents a type definition. The name attribute specifies the name of the new type. The Type element specifies it in terms of other types. The descriptive> element provides its documentation if any. The id attribute specifies the absolute scoped name of the typedef.

<!ELEMENT Typedef (webidl, descriptive?, ExtendedAttributeList?, Type) >
<!ATTLIST Typedef name CDATA #REQUIRED
                  id CDATA #REQUIRED >

Implements

An Implements represents Web IDL's ScopedName implements ScopedName; syntax. The name1 and name2 attributes give the first and second scoped names respectively. The descriptive> element provides the Implements's documentation if any.

<!ELEMENT Implements (webidl, descriptive?, ExtendedAttributeList?) >
<!ATTLIST Implements name1 CDATA #REQUIRED
                     name2 CDATA #REQUIRED >

Const

Const represents Web IDL's const Type identifier = ConstExpr; syntax. The Type specifies the constant's type, the name attribute specifies the constant's name, and the value attribute specifies its value. The descriptive> element provides the Const's documentation if any. The id attribute specifies the absolute scoped name of the const.

<!ELEMENT Const (webidl, descriptive?, ExtendedAttributeList?, Type) >
<!ATTLIST Const name CDATA #REQUIRED
                value CDATA #REQUIRED
                id CDATA #REQUIRED >

Stringifier

A Stringifier represents the Web IDL stringifier; syntax as an interface member. The descriptive> element provides the Stringifier's documentation if any.

<!ELEMENT Stringifier (descriptive?, ExtendedAttributeList) >

Attribute

An Attribute represents an attribute as an interface member. The Type element specifies its type. The name attribute specifies its name. Each of the stringifier and readonly attributes is set to a value the same as the attribute name when the corresponding keyword appears in the Web IDL input.

The GetRaises and SetRaises elements each provide a list of scoped names used in the corresponding clause in the Web IDL input.

The descriptive> element provides the attribute's documentation if any. The id attribute specifies the absolute scoped name of the attribute.

<!ELEMENT Attribute (webidl, descriptive?, ExtendedAttributeList?, Type,
    GetRaises?, SetRaises?) >
<!ATTLIST Attribute stringifier (stringifier) #IMPLIED
                    readonly (readonly) #IMPLIED
                    name CDATA #REQUIRED
                    id CDATA #REQUIRED >

<!ELEMENT GetRaises (RaiseException+) >

<!ELEMENT SetRaises (RaiseException+) >

<!ELEMENT RaiseException (descriptive?) >
<!ATTLIST RaiseException name CDATA #REQUIRED >

Operation

An Operation represents a method on interface. The Type element specifies its return type. The name attribute specifies its name.

Each of the stringifier, omitable, getter, setter, creator, deleter and caller attributes is set to a value the same as the attribute name when the corresponding keyword appears in the Web IDL input.

The Raises element provides a list of scoped names used in the corresponding clause in the Web IDL input.

The descriptive> element provides the attribute's documentation if any. The id attribute specifies the absolute scoped name of the operation.

An Argument is an argument to an operation. The Type element specifies its type. The name attribute specifies its name.

Each of the in, optional and ellipsis attributes is set to a value the same as the attribute name when the corresponding syntax appears in the Web IDL input.

<!ELEMENT Operation (webidl, descriptive?, ExtendedAttributeList?,
        Type, ArgumentList, Raises?) >
<!ATTLIST Operation stringifier (stringifier) #IMPLIED
                    omitable (omitable) #IMPLIED
                    getter (getter) #IMPLIED
                    setter (setter) #IMPLIED
                    creator (creator) #IMPLIED
                    deleter (deleter) #IMPLIED
                    caller (caller) #IMPLIED
                    name CDATA #REQUIRED
                    id CDATA #REQUIRED >

<!ELEMENT Raises (RaiseException+) >

<!ELEMENT ArgumentList (Argument*) >

<!ELEMENT Argument (descriptive?, ExtendedAttributeList?, Type) >
<!ATTLIST Argument in (in) #IMPLIED
                   optional (optional) #IMPLIED
                   ellipsis (ellipsis) #IMPLIED
                   name CDATA #REQUIRED >

Extended attributes

An ExtendedAttributeList contains one or more ExtendedAttribute element. Each ExtendedAttribute has:

a name attribute giving the name of the extended attribute;
if the extended attribute contains an = sign followed by a value, a value attribute giving the value, which is a scoped name or an identifier;
if the extended attribute contains parentheses (either with or without an = sign), an ArgumentList element giving the contents of the parentheses.

If the value attribute and the ArgumentList element are both present, then value must give an identifier rather than a scoped name.

<!ELEMENT ExtendedAttributeList (ExtendedAttribute+) >

<!ELEMENT ExtendedAttribute (ArgumentList?) >
<!ATTLIST ExtendedAttribute name CDATA #REQUIRED
                            value CDATA #IMPLIED >

Type

Type represents a type. It has one of these forms:

The any, object and void types have the attribute type set to the type, and no other attributes or elements. Note that the void type appears only when the Type element is a child of Operation.
A type that is an interface has the attribute name set to the name of that interface, and no other attributes or elements.
For the primitive types short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, boolean, octet and DOMString, there is an attribute type whose value is one of those strings, and no other attributes or elements. However, if the type was specified in the Web IDL with a trailing ? sign, then there is an attribute nullable with the value nullable.
For a sequence type, the Type contains an element Type giving the sequence element type, and no other attributes or elements. However, if the type was specified in the Web IDL with a trailing ? sign, then there is an attribute nullable with the value nullable.

The restrictions on which combinations of elements and attributes are permitted are not encoded by the DTD.

The descriptive> element provides the documentation if any, when the Type is a child of Operation, and thus representing an operation's return type.

<!ELEMENT Type (descriptive?, Type?) >
<!ATTLIST Type type CDATA #IMPLIED
               name CDATA #IMPLIED
               nullable (nullable) #IMPLIED >

Descriptive elements

The following elements contain documentation, extracted from the Doxygen-like comments in the input. <param> derives only from a \param command used inside a \def-device-cap block; any other \param command is linked to a parameter (argument) of the method being documented.

<!ELEMENT descriptive (description | brief | throw | author
    | version | Code | api-feature | device-cap | def-api-feature
    | def-api-feature-set | def-device-cap | def-instantiated | param)* >

<!ELEMENT description %Block; >

<!ELEMENT brief %Inline; >

<!ELEMENT throw %Inline; >

<!ELEMENT author %Inline; >

<!ELEMENT version %Inline; >

<!ELEMENT Code %Inline; >

<!ELEMENT api-feature %Inline; >
<!ATTLIST api-feature identifier CDATA #REQUIRED >

<!ELEMENT device-cap %Inline; >
<!ATTLIST device-cap identifier CDATA #REQUIRED >

<!ELEMENT param %Inline; >
<!ATTLIST param identifier CDATA #REQUIRED >

<!ELEMENT def-api-feature (descriptive?) >
<!ATTLIST def-api-feature identifier CDATA #REQUIRED >

<!ELEMENT def-api-feature-set (descriptive?) >
<!ATTLIST def-api-feature-set identifier CDATA #REQUIRED >

<!ELEMENT def-instantiated (descriptive?) >

<!ELEMENT def-device-cap (descriptive?) >
<!ATTLIST def-device-cap identifier CDATA #REQUIRED >

<!ELEMENT ref (#PCDATA) >

XHTML elements

The following XHTML elements are part of widlprocxml:

<!ELEMENT a %Inline; >
<!ATTLIST a href CDATA #REQUIRED >

<!ELEMENT b %Inline; >

<!ELEMENT br EMPTY >

<!ELEMENT dd %Flow; >

<!ELEMENT dl ((dt | dd)*) >

<!ELEMENT dt %Inline; >

<!ELEMENT em %Inline; >

<!ELEMENT li %Flow; >

<!ELEMENT p %Inline; >

<!ELEMENT table (tr*) >

<!ELEMENT td %Flow; >

<!ELEMENT th %Flow; >

<!ELEMENT tr ((th | td)*) >

<!ELEMENT ul (li*) >

Bibliography

BONDI - an open source industry collaboration for widget and web technologies, http://bondi.omtp.org/

Doxygen Source code documentation generator tool, http://www.stack.nl/~dimitri/doxygen/index.html

W3C Geolocation API Specification Editor's Draft 3 April 2009, http://dev.w3.org/geo/api/spec-source.html

Web IDL W3C Editor's Draft 30 September 2009, http://dev.w3.org/2006/webapi/WebIDL