Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
editorial: Define API section more normatively and with more <dfn>s
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.
- Loading branch information