-
Notifications
You must be signed in to change notification settings - Fork 32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
editorial: Define API section more normatively and with more <dfn>s #120
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Bikeshed's 'foo' and ''foo'' shorthands for CSS sometimes cause problems in this spec because of our use of "Z - X' - Y''" angles. Since this specification is totally unrelated to CSS, we can just disable those shorthands.
…ction - Talk about linear acceleration, which is usually more useful than acceleration with gravity, first. - Move the sentence that discusses why an implementation might choose to provide absolute orientation data to the Model section.
reillyeon
approved these changes
Nov 10, 2023
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.
rakuco
force-pushed
the
editorial/section-division-more-dfns
branch
from
November 13, 2023 17:56
e188fd8
to
f0ff533
Compare
github-actions bot
added a commit
that referenced
this pull request
Nov 13, 2023
SHA: c0bb08a Reason: push, by rakuco Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 normativedescriptions rather than the IDL blocks.
attributes and methods.
<div algorithm>
around the existing requestPermission() algorithmsto highlight variables.
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 thedefault values are set. This is not the case for a few DeviceMotionEvent
attributes due to issue DeviceMotionEvent atttributes can't be null per current IDL #91.
More normative definitions:
<dfn>
for "significant change in orientation". Although eachimplementation still gets to decide its meaning, we can now reference
the term from other parts of the spec. The same requirements and
suggestions remain.
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.
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.
<dfn>
s from the ondeviceorientationabsolutesubsection as well.
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.
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.
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.
Preview | Diff