Skip to content

Commit

Permalink
editorial: Define API section more normatively and with more <dfn>s
Browse files Browse the repository at this point in the history
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
Raphael Kubo da Costa committed Nov 10, 2023
1 parent d7c9e0d commit c0a2640
Showing 1 changed file with 151 additions and 40 deletions.
Loading

0 comments on commit c0a2640

Please sign in to comment.