This is a PR with multiple commits for clarity, but the really important one is the last one, whose commit message I'll reproduce here. Having this structure in place makes it a lot easier to add permissions policy integration or make the Permissions API integration required, for example.
The idea is to make this section less hand-wavy and easier to change in the
future by defining algorithms and steps more clearly while not making any
user-visible changes.
Readability:
Rename the "Description" section to "API"
Start each "API" subsection with an IDL block rather than prose.
Move the <dfn>s for attributes and methods to their normative
descriptions rather than the IDL blocks.
Use the wording currently recommended by the Web IDL spec to define
attributes and methods.
Add <div algorithm> around the existing requestPermission() algorithms
to highlight variables.
Explain what each Device{Motion,Orientation}Event attribute represents in
each definition instead of doing so separately later in each subsection.
Where possible, stop saying what each attribute must be initialized to on
creation, as DOM's event construction steps guarantee that they will be
initialized by their respective *EventInit dictionaries, where the
default values are set. This is not the case for a few DeviceMotionEvent
attributes due to issue #91.
More normative definitions:
Device Orientation
Add a <dfn> for "significant change in orientation". Although each
implementation still gets to decide its meaning, we can now reference
the term from other parts of the spec. The same requirements and
suggestions remain.
Define a "fire an orientation event" algorithm that normatively
specifies the process of obtaining device's absolute or relative
orientation data in the format used by the spec, limiting its precision
and firing a DeviceOrientationEvent that is constructed and has its
attributes initialized as described by the DOM spec.
Attempt to define what the event target of the event is: this
specification is an outlier in how the event handlers are part of the
Window interface -- it is difficult to indicate which Window object the
event is fired at. For now, use "a navigable's active window". This is
not airtight since we do not specify which navigable this is referring
to (it's basically "all navigables"), but I could not think of a better
way to specify this.
Reference the new <dfn>s from the ondeviceorientationabsolute
subsection as well.
Device Motion
Add separate subsections for each interface. The
DeviceMotionEvent{Acceleration,RotationRate} interfaces have proper
"associated data" (or internal slots) that are referenced from the
attribute getter descriptions. The two interfaces now have a short
description of what they represent as well.
Define the process of firing a DeviceMotionEvent as an algorithm with a
proper set of steps instead of just saying implementations must fire the
"devicemotion" event. The steps are also responsible for limiting the
precision of the data and firing a DeviceMotionEvent that is constructed
and has its attributes initialized as described by the DOM spec.
As with the Device Orientation part, an attempt has been made to define
what the event target of the event is, as it is difficult to indicate
which Window object the event is fired at. For now, use "a navigable's
active window". This is not airtight since we do not specify which
navigable this is referring to (it's basically "all navigables"), but I
could not think of a better way to specify this.
This is a PR with multiple commits for clarity, but the really important one is the last one, whose commit message I'll reproduce here. Having this structure in place makes it a lot easier to add permissions policy integration or make the Permissions API integration required, for example.
The idea is to make this section less hand-wavy and easier to change in the future by defining algorithms and steps more clearly while not making any user-visible changes.
Readability:
<dfn>s for attributes and methods to their normative descriptions rather than the IDL blocks.<div algorithm>around the existing requestPermission() algorithms to highlight variables.*EventInitdictionaries, where the default values are set. This is not the case for a few DeviceMotionEvent attributes due to issue #91.More normative definitions:
<dfn>for "significant change in orientation". Although each implementation still gets to decide its meaning, we can now reference the term from other parts of the spec. The same requirements and suggestions remain.<dfn>s from the ondeviceorientationabsolute subsection as well.Preview | Diff