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...

Introduction

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>.

Unsupported

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:

Interfaces

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

Constructors on interfaces

        [Something,
         Constructor,
         Constructor(boolean bar, sequence<double> foo, Promise<double> blah)]
        interface SuperStar {};
      
        [Constructor] interface SuperStar {};
      

NamedConstructors

NamedConstructors on interfaces

        [Something,
         NamedConstructor=Sun(),
         NamedConstructor=Sun(boolean bar, Date[][][] foo)]
        interface SuperStar {};
      

Constants

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.

Attributes

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.

Operations

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).

Serializer

        interface SerializerMap {
          attribute DOMString foo;
          attribute DOMString bar;
          serializer = { foo, bar };
        };
      

serializer serializes a SerializerMap.

Comments

        interface SuperStar {
          // This is a comment
          // over two lines.
        };
      

Dictionaries

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

Exceptions

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

Enumerations

Basic enumeration.

        enum EnumBasic {
          // 1
          "one",
          // 2
          "two",
          // 3
          "three",
          // 4
          "white space"
        };
      

EnumBasic

Callbacks

Basic callback.

        callback SuperStar = void();
      

Less basic callback.

        callback CbLessBasic = unsigned long long?(optional any value);
      

CbLessBasic

Typedefs

Basic typedef.

        typedef DOMString string;
      

Less basic typedef.

        typedef [Something] unsigned long long? tdLessBasic;
      

tdLessBasic

Implements

Basic implements.

        Window implements Breakable;
      

Less basic implements.

        [Something]Window implements Breakable;