This fake spec tried to exercise all aspects of WebIDL so as to do regression testing in this complex piece of code.
CUSTOM PARAGRAPH
interface Foo { attribute DOMString attr; };
The attr attribute's getter must...
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"><code>turnAround</code> member of the
<code>Dahut</code> interface</dfn>
. We can also link to
some constant with
<a for="Dahut" data-lt="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. Its overloaded form can be refered to specifically using <dfn data-lt="MethBasic.ull!overload-1">
(where overload-1
refers to the 1st overloaded version of the method; more can be added).
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;