10. WebIDL Processing
Bikeshed can automatically process IDL blocks, marking up all relevant terms for you without any intervention, setting up definitions and autolinks as appropriate.
To activate this behavior,
simply place the IDL in the dfn and a elements.
< xmp class = idl > sequence< Foo > /etc types.
This prevents you from using other markup in your IDL,
but that’s relatively rare.
For IDL specifically, you can also use
In the process of doing this, Bikeshed will also syntax-check your IDL, and report fatal errors for any mistakes. Bikeshed’s IDL parser, courtesy of Peter Linss, is intended to be forward-compatible with IDL changes, gracefully emitting unknown constructs unchanged and recovering as well as it can. If anything isn’t recognized when it should be, or the parser fails in a major, non-graceful way, please report it as an issue.
10.1. Putting Definitions Elsewhere
Quite often, you may want to have the actual definition of an IDL term (the thing that Bikeshed actually links to) somewhere in your prose near the full definition, rather than being in the IDL block.
Bikeshed will automatically produce an a in your IDL,
rather than a dfn,
if it can find a pre-existing definition of that IDL term,
including local definitions in the current spec.
However, you have to mark up the definition correctly to get this to work,
or else Bikeshed will fail to recognize there’s an external definition
and will mark up the IDL with a dfn as well.
In particular, method and attribute definitions need to have their for value set to the interface they’re a part of
(and similar with dictionary members).
Methods have some further complexity -
they should have their definition text set to contain the names of all their arguments.
For example, take the following example IDL:
interface Foo {
undefined bar(DOMString baz, optional long qux);
};
To have Bikeshed recognize a definition for the bar() method placed elsewhere,
it must look something like
Additionally, it should define alternate linking texts for omittable arguments,
like optional, or are variadic (like long... qux), or have a default value.
Nullable arguments (like long? qux) are not omittable.
(If you are fine with the dfn being in the IDL block,
Bikeshed will do all of this for you.)
Unless all arguments can be omitted, the definition text should not have an alternative with empty args.
For convenience, however, Bikeshed will allow autolinks with empty argument lists to work,
as long as it can resolve the link unambiguously.
For example, {{Foo/bar()}} will autolink to the method defined above,
despite it not being a valid call signature,
as long as there isn’t an overload of bar() that it might also apply to.
(The above applies to all functionish types: method, constructor, stringifier, etc.)
Marking up argument definitions is similar.
To mark up the baz argument of the above method, for example,
do
10.1.1. Free Type/Etc Documentation on Attributes/Dict Members
Bikeshed automatically gathers information from your IDL block about attributes and dictionary members, such as their type, their default value, and whether they’re readonly or nullable. You can have Bikeshed automatically output that information in your definition elsewhere, by using a specific markup structure:
< dl dfn-type = attribute dfn-for = FooInterface > < dt >< dfn > fooAttr</ dfn > < dd > ...< dt >< dfn > barAttr</ dfn > < dd > ...</ dl >
If an attribute or dictionary member is defined in a dt element,
and is the sole content of that element,
Bikeshed will automatically add useful information about the attribute following it.
You can also invoke this manually,
by adding a data-dict-member-info for dictionary members).
10.2. Linking to Stringifiers
Linking to a stringifier is a little complicated, because WebIDL allows four different syntaxes for it.
The stringifier keyword itself is always linkable;
it’s a "dfn" type definition with for=MyInterface
and linking text "stringification behavior".
Like any other IDL construct,
you can instead define the term yourself in the same way,
and the IDL will link to your definition instead,
like
If you use the "stringifier attribute" form,
like stringifier attribute DOMString href;,
you can also just link/dfn the attribute as normal.
If you use the "stringifier method" form,
like stringifier DOMString foo(long bar);,
you can also just link/dfn the method as normal,
like
If you use the "anonymous stringifier method" form,
like stringifier DOMString(long bar),
you can still technically link/dfn it as a stringifier method.
It doesn’t have a name, so we invent one -
it’s called __stringifier__(), a la Python’s magic methods.
(Note the two underscores on each side.)
You should almost never need to do this;
the only reason to need to specify the method name
(rather than just linking to the keyword, as described above)
is if you’re linking/dfning an argument to the method,
and need to specify a for value for it.
10.3. Turning Off Processing
If for whatever reason you don’t want your IDL block to be processed by Bikeshed,
simply use another element, or another class.
If you really want to use data-no-idl attribute to the element.
Bikeshed will leave these elements alone.
Alternately, if your block is IDL,
but it’s not meant to be taken literally
(for example, if it shows an example attribute,
then explains in prose the set of actual attribute names to be used,
as in the _camel_cased_attribute in CSSOM),
put a class=extract on it.
