This fake spec tried to exercise all aspects of WebIDL so as to do regression testing in this complex piece of code.
CUSTOM PARAGRAPH
To document an interface using contiguous IDL, first write your WebIDL in a <pre class="idl">
block:
<pre class="idl"> [Constructor] interface Dahut : Mammal { const unsigned short LEVROGYROUS = 0; const unsigned short DEXTROGYROUS = 1; readonly attribute DOMString chirality; attribute unsigned long age; Dahut turnAround(float angle, boolean fall); unsigned long trip(); void yell([AllowAny] unsigned long volume, [TreatNullAs=EmptyString] DOMString sentence); }; </pre>
This is pretty-printed as:
[Constructor] interface Dahut : Mammal { const unsigned short LEVROGYROUS = 0; const unsigned short DEXTROGYROUS = 1; readonly attribute DOMString chirality; attribute unsigned long age; Dahut turnAround(float angle, boolean fall); unsigned long trip(); void yell([AllowAny] unsigned long volume, [TreatNullAs=EmptyString] DOMString sentence); };
Then document the interface and its fields using
<dfn>interface-name</dfn>
and
<dfn>interface-name.member-name</dfn>
.
For example, to discuss Dahut, you'd write <dfn>Dahut</dfn>
,
and to document Dahut.trip, you'd write
<dfn>Dahut.trip</dfn>
.
This also automatically links the IDL declaration to the prose definition.
You can also link to IDL terms in a similar way.
<a>Dahut.trip</a>
will link to the definition above:
Dahut.trip.
If you have a whole paragraph about a single interface, you can also set the dfn-for
or link-for
attribute on any ancestor
element of the <dfn>
or <a>
element, respectively. Since this paragraph
defines members of Dahut, its tag is <p dfn-for="Dahut" link-for="Dahut">
,
which allows a simple <dfn>chirality</dfn>
tag to
define the chirality attribute and a simple
<a>LEVROGYROUS</a>
tag to link to the LEVROGYROUS
constant.
Finally, if you need a one-off definition or link whose text isn't
exactly the IDL entity it's discussing, you can specify the for
and/or title
attributes directly on the <dfn>
or
<a>
tag, similarly to when
defining or
linking to a non-IDL term. The
turnAround
member of the Dahut
interface can
be defined with <dfn for="Dahut"
title="turnAround"><code>turnAround</code> member of the
<code>Dahut</code> interface</dfn>
. We can also link to
some constant with
<a for="Dahut" title="LEVROGYROUS">some constant</a>
.
The following aspects of WebIDL are not currently supported and are not yet tested for:
Support for these features will likely be added later.
The following features are supposedly supported but actually buggy:
Things that still need to be done:
Basic interface.
interface SuperStar {};
Interface with extended attribute.
[Something, Constructor()] interface SuperStar {};
Interface with inheritance.
interface SuperStar : HyperStar {};
Partial interface.
partial interface SuperStar {};
Callback interface .
callback interface SuperStar {};
interface DocInterface {}; interface DocIsNotCaseSensitive {}; interface UndocInterface {};
DocInterface is an interface and so is DoCiSnOtCaSeSeNsItIvE.
Constructors on interfaces
[Something, Constructor, Constructor(boolean bar, sequence<double> foo, Promise<double> blah)] interface SuperStar {};
[Constructor] interface SuperStar {};
NamedConstructors on interfaces
[Something, NamedConstructor=Sun(), NamedConstructor=Sun(boolean bar, Date[][][] foo)] interface SuperStar {};
All constants and some type testing
interface ConstTest { // 1 const boolean test = true; // 2 const byte bite = 8; // 3 const octet eight = 7; // 4 const short small = 42; // 5 const unsigned short shortish = 250; // 6 const long notSoLong = 99999; // 7 const unsigned long somewhatLong = 9999999; // 8 const long long veryLong = 9999999999999; // 9 const unsigned long long soLong = 99999999999999999; // 10 const float ationDevice = 4.2; // 11 const unrestricted float buoy = 4.2222222222; // 12 const double twice = 4.222222222; // 13 const unrestricted double rambaldi = 47.0; // 14 const boolean? why = false; // 15 const boolean? notSo = null; // 16 const short inf = Infinity; // 17 const short mininf = -Infinity; // 18 const short cheese = NaN; // 18 [Something] const short extAttr = NaN; };
rambaldi is a constant and so are why and this other thing.
Basic attributes testing.
interface AttrBasic { // 1 attribute DOMString regular; // 2 readonly attribute DOMString ro; // 2.2 readonly attribute DOMString _readonly; // 2.5 inherit attribute DOMString in; // 2.7 stringifier attribute DOMString st; // 3 [Something] readonly attribute DOMString ext; // 3.5 attribute Date[] dates; // 4.0 attribute Promise<DOMString> operation; };
readonly and regular are attributes.
Basic operations testing.
interface MethBasic { // 1 void basic(); // 2 [Something] void ext(); // 3 unsigned long long ull(short s); // 3.5 SuperStar? ull(); // 4 // Parameters: // one: 4.1 // ext: 4.1 // maybe: 4.2 // shorts: 4.3 // hypercubes: 4.3 // defaulted: 4.3 // defaulted2: 4.3 // variable: 4.last SuperStar[][][][] paramed(SuperStar[][]?[] one, [ExtAttrs] ByteString? ext, optional short maybe, short[] shorts, short[][][][] hypercubes, optional short defaulted = 3.5, optional DOMString defaulted2 = "one", short... variable); };
ull is a method.
interface SerializerMap { attribute DOMString foo; attribute DOMString bar; serializer = { foo, bar }; };
serializer serializes a SerializerMap.
interface SuperStar { // This is a comment // over two lines. };
Basic dictionary.
dictionary SuperStar {};
Inheriting dictionary.
dictionary SuperStar : HyperStar {};
Data in dictionary.
dictionary SuperStar { // 1 DOMString value; // 2 DOMString? nullable; // 3 [Something]float ext; // 4 unsigned long long longLong; // 5 boolean test = true; // 7 byte little = 2; // 8 byte big = Infinity; // 9 byte cheese = NaN; // 10 DOMString blah = "blah blah"; };
dictionary DictDocTest { DOMString dictDocField; DOMString? otherField; long undocField; };
DictDocTest contains dictDocField and otherField
Basic exception.
exception SuperStar {};
Inheriting exception.
exception SuperStar : HyperStar {};
Exception with content.
exception ExFields { // 1 [Something]const SuperStar value = 42; // 2 SuperStar? message; // 3 sequence<SuperStar> floats; // 4 SuperStar[][] numbers; // 5 Promise<SuperStar> stars; };
ExFields contains value and floats
Basic enumeration.
enum EnumBasic { // 1 "one", // 2 "two", // 3 "three", // 4 "white space" };
EnumBasic
Basic callback.
callback SuperStar = void();
Less basic callback.
callback CbLessBasic = unsigned long long?(optional any value);
CbLessBasic
Basic typedef.
typedef DOMString string;
Less basic typedef.
typedef [Something] unsigned long long? tdLessBasic;
tdLessBasic
Basic implements.
Window implements Breakable;
Less basic implements.
[Something]Window implements Breakable;