Consider better styling for API intro notes #907
Labels
editorial
Changes that do not affect how the standard is understood
Comments
domenic
added
the
editorial
|
I think "Not everything is italic" is the biggest selling point for me 😄. We'd need at least two types, because some of our notes are for implementers. The DOM spec example looks more like our "Class definitions" than our "Note" sections. Moving usage notes into the "Class definition" and rewriting it in that style might be a way forward. |
|
My latest take on this is in https://domenic.github.io/async-local-storage/; see e.g. https://domenic.github.io/async-local-storage/#storagearea-set. I'm undecided on whether we should have these domintro blocks in the method definitions (as the current notes or), or if we should consolidate them all into one place per class. A nice feature of the latter is that it allows us to replace the class definitions, which have caused significant confusion (#45, #732, and some recent IRC conversations). |
|
I like the way it looks in your async-local-storage draft. You still have a class definition in the current draft. I think they should not get nuked as they make the spec very navigational (provided that they get linked up in the same way I’ve done in #872 and #913). (edit: Just realized that the “see below” is a link. Could be enough, but it seems more intuitive to me to make the method name itself a link.) |
|
That's a bit different, as there it's used to normatively create the class. I think if all the domintros were consolidated into one block (see e.g. below the IDL block at https://dom.spec.whatwg.org/#interface-abortcontroller) then having the class definition nearby would be just redundant. So that's why we'd get to nuke the class definition. If we keep them spread out, as I've done in async-local-storage, then yeah, the class definition or some similar table of contents (perhaps just the normal table of contents?) would be needed. |
|
I acknowledge that all the info a developer would need is in there. I feel a bit hesitant about diverging from other specs which also have IDL or at least some sort of code-y representation. It feels like it doesn’t skim-read very well, but maybe it’s just because I am not used to that layout. So I am cool with your approach, but I still do like the clickable class definitions. |
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * All methods and accesors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
11 tasks
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * All methods and accesors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
domenic
added a commit
that referenced
this issue
Jun 11, 2020
Closes #963. Normative changes to widely-implemented features, roughly in order of most disruptive to least-disruptive: * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. In particular this means that attempts to set either of them post-creation will throw a TypeError. Chromium already ships these semantics. * Functions which take a dictionary no longer accept non-objects. * For the queuing strategy classes, their highWaterMark property will no longer return a non-number from their highWaterMark properties, if one was passed to the constructor. Instead, NaN will be returned. * All methods and accessors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. Closes #952. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. * Property lookup in options arguments now happens earlier, at argument-conversion time, and in alphabetical order, per dictionary rules. Normative changes to unimplemented features: * ReadableStream's getIterator() method has been renamed to values() as part of adopting Web IDL's infrastructure for async iterators. * The byobRequest property on ReadableByteStreamController now returns null when there is no BYOB request, instead of returning undefined. * The view property on ReadableStreamBYOBRequest now returns null when the view cannot be written into, instead of returning undefined. * Various byte-stream-related APIs that used to specifically prohibit detached buffers now check for zero-length views or buffers, which is a more general category. * The async iterator's next() and return() methods now behave more like async generators, e.g. returning promises fulfilled with { value: undefined, done: true } after return()ing the iterator, instead of returning a rejected promise. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. Closes #963. Closes #1017. See #1036 for further followup on the iteration result objects. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
yutakahirano
pushed a commit
to yutakahirano/streams
that referenced
this issue
Jun 3, 2021
Closes whatwg#963. Normative changes to widely-implemented features, roughly in order of most disruptive to least-disruptive: * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes whatwg#1005. In particular this means that attempts to set either of them post-creation will throw a TypeError. Chromium already ships these semantics. * Functions which take a dictionary no longer accept non-objects. * For the queuing strategy classes, their highWaterMark property will no longer return a non-number from their highWaterMark properties, if one was passed to the constructor. Instead, NaN will be returned. * All methods and accessors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes whatwg#586. * All classes now have [Symbol.toStringTag] properties. Closes whatwg#952. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. * Property lookup in options arguments now happens earlier, at argument-conversion time, and in alphabetical order, per dictionary rules. Normative changes to unimplemented features: * ReadableStream's getIterator() method has been renamed to values() as part of adopting Web IDL's infrastructure for async iterators. * The byobRequest property on ReadableByteStreamController now returns null when there is no BYOB request, instead of returning undefined. * The view property on ReadableStreamBYOBRequest now returns null when the view cannot be written into, instead of returning undefined. * Various byte-stream-related APIs that used to specifically prohibit detached buffers now check for zero-length views or buffers, which is a more general category. * The async iterator's next() and return() methods now behave more like async generators, e.g. returning promises fulfilled with { value: undefined, done: true } after return()ing the iterator, instead of returning a rejected promise. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. Closes whatwg#963. Closes whatwg#1017. See whatwg#1036 for further followup on the iteration result objects. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes whatwg#885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes whatwg#907. * Abstract operations are now consistently alphabetized within their section. Closes whatwg#684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes whatwg#687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes whatwg#965.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Compare the green notes at https://streams.spec.whatwg.org/#rs-prototype to those right below https://dom.spec.whatwg.org/#event-path.
We're different than them in that we only do one API per section, so at first glance that list style isn't that necessary. But the "domintro" style shown there is a bit better than ours in a few ways:
[, x]to denote optionality, or spell out dictionaries even if the standard treats them as a single variable, or show thattee()s return value is usually used with destructuring, or insertawaitbefore promise-returning method calls... Could be nice.Should we adapt? Should we do anything different than most specs do, because of our one-API-per-section nature? Thoughts appreciated. Once we have a plan, I'd like to turn this into a "good first bug".
The text was updated successfully, but these errors were encountered: