Tim Renouf, Aplix Corp
$Id$
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.
widlproc filename
widlproc reads the file named filename, and sends its XML output format to stdout.
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.
double is allowed as a DeclarationType or a BoxedType.
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.)
Each Doxygen comment block refers to a comment referral point in the Web IDL, one of module, interface, exception, const, attribute, operation or argument.
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.
The maximal sequence of inline comments (delimited by //)
on adjacent lines, where all of the following conditions hold:
/ of ! or
a third /;
<
(see below), or none does;
< (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.
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.
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.
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.
Declares a name for the document node associated with the current referral point. This is useful for the root document node that otherwise does not have a WebIDL identifier.
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.)
This renders the next word as bold. It is equivalent to enclosing the
next word with <b> </b>.
Starts a new paragraph. The remainder of the paragraph contains a brief description of the entity being documented.
\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.
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.
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.
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.
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.
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.
Creates a line break in the output.
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.
Starts a new paragraph. The remainder of the paragraph is made to refer to the return type of the entity being documented.
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).
Starts a new paragraph. The remainder of the paragraph contains version number information.
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.
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
ol
p
table
ul
The following HTML inline elements are accepted:
a
img
b
br
em
The following HTML elements are accepted where valid inside one of the
other elements:
dd
dt
li
td
th
tr
The output of widlproc is an XML representation of the Web IDL, with added XML elements representing the Doxygen-like comments.
<!-- Autogenerated from widlproc.html : do not edit. -->
<!ENTITY % block 'dl | p | table | ul' > <!ENTITY % Block '(%block;)*' > <!ENTITY % inline 'a | b | br | em | img' > <!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 is the root element of the XML document.
The ExtendedAttributeList specifies any extended attributes for the Interface, Dictionary, Exception, Typedef, Valuetype or Const in the Definition.
<!ELEMENT Definitions ( webidl, descriptive?, (Interface | Dictionary | Callback
| Enum | Exception | Typedef | Implements)*) >
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 partial attribute indicates that the definition of the interface complements an existing definition. The callback attribute specificies that a given interface is a callback 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 | Attribute | Operation | Stringifier* | Serializer* | Iterator | IteratorObject)* ) >
<!ATTLIST Interface name CDATA #REQUIRED
partial (partial) #IMPLIED
callback (callback) #IMPLIED
id CDATA #REQUIRED >
<!ELEMENT InterfaceInheritance (Name+) >
<!ELEMENT Name EMPTY >
<!ATTLIST Name name CDATA #REQUIRED >
A Dictionary represents a dictionary. The name attribute specifies the name of the dictionary. The descriptive element provides its documentation if any. The id attribute specifies the absolute scoped name of the dictionary.
The partial attribute indicates that the definition of the interface complements an existing definition.
The DictionaryInheritance element indicates that the dictionary inherits from other dictionary(s). Each Name in the DictionaryInheritance has a name attribute giving the scoped name of the dictionary being inherited from.
<!ELEMENT Dictionary (webidl, descriptive?, DictionaryInheritance?, DictionaryMember* ) >
<!ATTLIST Dictionary name CDATA #REQUIRED
partial (partial) #IMPLIED
id CDATA #REQUIRED >
<!ELEMENT DictionaryInheritance (Name+) >
A Callback represents a callback type. The name attribute specifies the name of the dictionary. The descriptive element provides its documentation if any.
The Type element specifies its return type.
An Argument is an argument to an operation. The Type element specifies its type. The name attribute specifies its name if it has one.
<!ELEMENT Callback (webidl, descriptive?, Type, ArgumentList? ) >
<!ATTLIST Callback name CDATA #REQUIRED
id CDATA #REQUIRED>
An Enum represents an enumeration. The name attribute specifies the name of the enumeration. The descriptive element provides its documentation if any.
The EnumValue element indicates the values defined for that enumeration in its stringvalue attribute.
<!ELEMENT Enum (webidl, descriptive?, EnumValue* ) >
<!ATTLIST Enum name CDATA #REQUIRED
id CDATA #REQUIRED >
<!ELEMENT EnumValue (webidl, descriptive?) >
<!ATTLIST EnumValue stringvalue CDATA #REQUIRED >
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.
The ExceptionInheritance element indicates that the exception inherits from another exception. The Name in the ExceptionInheritance has a name attribute giving the scoped name of the exception being inherited from.
<!ELEMENT Exception (webidl, descriptive?, ExtendedAttributeList?, ExceptionInheritance?,
(Const | ExceptionField)* ) >
<!ATTLIST Exception name CDATA #REQUIRED
id CDATA #REQUIRED >
<!ELEMENT ExceptionInheritance (Name) >
<!ELEMENT ExceptionField (webidl, descriptive?, ExtendedAttributeList?, (Type)) >
<!ATTLIST ExceptionField name CDATA #REQUIRED
id CDATA #REQUIRED >
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 >
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 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 #IMPLIED
id CDATA #REQUIRED >
A Stringifier represents the Web IDL stringifier;
syntax as an interface member.
The descriptive> element
provides the Stringifier's documentation if any.
<!ELEMENT Stringifier (webidl, descriptive?, ExtendedAttributeList?) >
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, static 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 inherit attribute is set to inherit when the attribute inherits its getter.
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)) >
<!ATTLIST Attribute stringifier (stringifier) #IMPLIED
readonly (readonly) #IMPLIED
inherit (inherit) #IMPLIED
static (static) #IMPLIED
name CDATA #REQUIRED
id CDATA #REQUIRED >
An Operation represents a method on interface. The Type element specifies its return type. The name attribute specifies its name.
Each of the stringifier, static, getter, setter, creator, deleter and legacycaller, serializer attributes is set to a value the same as the attribute name when the corresponding keyword appears 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 if it has one.
An Argument is an argument to an operation. The Type element specifies its type. The name attribute specifies its name if it has one.
Each of the 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.
The value attribute used on optional arguments specifies default value for non-string values, and stringvalue for string values.
<!ELEMENT Operation (webidl, descriptive?, ExtendedAttributeList?,
(Type), ArgumentList) >
<!ATTLIST Operation stringifier (stringifier) #IMPLIED
static (static) #IMPLIED
getter (getter) #IMPLIED
setter (setter) #IMPLIED
creator (creator) #IMPLIED
deleter (deleter) #IMPLIED
serializer (serializer) #IMPLIED
legacycaller (legacycaller) #IMPLIED
name NMTOKEN #IMPLIED
id NMTOKEN #IMPLIED >
<!ELEMENT ArgumentList (Argument*) >
<!ELEMENT Argument (descriptive?, ExtendedAttributeList?, (Type)) >
<!ATTLIST Argument
optional (optional) #IMPLIED
ellipsis (ellipsis) #IMPLIED
value CDATA #IMPLIED
stringvalue CDATA #IMPLIED
name NMTOKEN #REQUIRED >
A Serializer represents a serializer for an interface, either defined in the prose or via a pattern.
The descriptive element provides the serializer's documentation if any.
The attribute attribute defines the attribute that is used for serialization if any.
The optional Map and List elements describe the pattern (if any) for the serializer. They take PatternAttribute elements with a name attribute that describes the attributes used for serialization.
Map elements take a pattern attribute that can be set to either "getter" (if the getter is used for serialization), "all" if all serializable attributes are to be used, or "selection" if the attributes named as children elements are to be used. Optionally, they take a inherit attribute set to "inherit" if the serialization takes also into account inherited attributes.
List elements take a pattern attribute that can be set to either "getter" (if the getter is used for serialization), or "selection" if the attributes named as children elements are to be used.
<!ELEMENT Serializer (webidl, descriptive?, ExtendedAttributeList?, (Map | List)?) >
<!ATTLIST Serializer attribute CDATA #IMPLIED >
<!ELEMENT Map ((PatternAttribute*)) >
<!ATTLIST Map inherit (inherit) #IMPLIED
pattern (getter|all|selection) #REQUIRED>
<!ELEMENT List ((PatternAttribute*)) >
<!ATTLIST List pattern (getter|selection) #REQUIRED>
<!ELEMENT PatternAttribute EMPTY>
<!ATTLIST PatternAttribute name CDATA #REQUIRED>
An Iterator element defines whether the interface has a custom iterator; the type of the iterated objects is defined in the Type child. If that interator implements a particular interface, the name of that interface is set in the interface attribute.
<!ELEMENT Iterator (webidl, descriptive?, ExtendedAttributeList?, Type) > <!ATTLIST Iterator interface CDATA #IMPLIED>
An IteratorObject element denotes that the interface serves as an iterator object interface; the type of the iterated objects is defined in the Type child.
<!ELEMENT IteratorObject (webidl, descriptive?, ExtendedAttributeList?, Type) >
A DictionaryMember represents a member of a dictionary. The Type element specifies its type. The name attribute specifies its name.
The descriptive> element provides the dictionary member's documentation if any. The id attribute specifies the absolute scoped name of the attribute.
The value attribute specifies its value for non-string values, and stringvalue for string values.
<!ELEMENT DictionaryMember (webidl, descriptive?, ExtendedAttributeList?, Type) >
<!ATTLIST DictionaryMember name CDATA #REQUIRED
id CDATA #REQUIRED
value CDATA #IMPLIED
stringvalue CDATA #IMPLIED >
An ExtendedAttributeList contains one or more ExtendedAttribute element. Each ExtendedAttribute has:
= sign followed by a
value, a value attribute giving the value, which is a scoped
name or an identifier;
= 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 (webidl, ArgumentList?) >
<!ATTLIST ExtendedAttribute name NMTOKEN #REQUIRED
value CDATA #IMPLIED >
Type represents a type. It has one of these forms:
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.
short, unsigned short,
long, unsigned long, long long,
unsigned long long, float, double,
boolean, octet, byte 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.
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.
The ExtendedAttributeList element provides the optional extended attributes that can be defined for a type through typedef, à la typedef [Clamp] octet Value;.
<!ELEMENT Type (descriptive?, ExtendedAttributeList?, Type*) >
<!ATTLIST Type type CDATA #IMPLIED
name NMTOKEN #IMPLIED
nullable (nullable) #IMPLIED >
For a sequence type, the Type element with an attribute type set to sequence contains an element Type giving the sequence element type, and no other attributes or elements. If the sequence is specified in the Web IDL with a trailing ?
sign, then there is an attribute nullable with the value
nullable.
For an array type, the Type element with an attribute type set to array contains an element Type giving the array element type. If the array is specified in the Web IDL with a trailing ?
sign, then there is an attribute nullable with the value
nullable.
For a union type, the Type element with an attribute type set to union contains at least two element Type giving the union members type. If the union is specified in the Web IDL with a trailing ?
sign, then there is an attribute nullable with the value
nullable.
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) >
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 img %Inline; >
<!ATTLIST img src CDATA #REQUIRED
alt CDATA #IMPLIED>
<!ELEMENT li %Flow; >
<!ELEMENT p %Inline; >
<!ELEMENT table (tr*) >
<!ELEMENT td %Flow; >
<!ELEMENT th %Flow; >
<!ELEMENT tr ((th | td)*) >
<!ELEMENT ul (li*) >
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 3 May 2011, http://dev.w3.org/2006/webapi/WebIDL