Open Elchi3 opened 1 year ago
I used WebRef to start building a list of concepts to document, that is, concepts actually in use. Some will lead to significant work; others should be reasonably quick to deal with.
(This list is a WIP)
[AllowShared]
WebIDL spec, §3.3.2 [Clamp]
WebIDL spec, §3.3.3 Related to [EnforceRange]
[CrossOriginIsolated]
WebIDL spec, §3.3.4[Default]
WebIDL spec, §3.3.5 Only for toJSON()
for now.[EnforceRange]
WebIDL spec, §3.3.6 Related to [Clamp]
[Exposed=…]
WebIDL spec, §3.3.7 With [Global]
and maybe [SecureContext]
, part of a realm initiative?[Global]
WebIDL spec, §3.3.8 With [Exposed]
and maybe [SecureContext]
, part of a realm initiative?[NewObject]
WebIDL spec, §3.3.9 Very common, related to [SameObject]
[PutForwards=…]
WebIDL spec, §3.3.10[Replaceable]
WebIDL spec, §3.3.11[SameObject]
WebIDL spec, §3.3.12 Very common, related to [NewObject]
[SecureContext]
WebIDL spec, §3.3.13 With [Global]
and [Exposed]
, maybe part of a realm initiative?[Unscopable]
WebIDL spec, §3.3.14[LegacyFactoryFunction]
WebIDL spec, §3.4.1[LegacyLenientSetter]
WebIDL spec, §3.4.2 [LegacyLenientThis]
WebIDL spec, §3.4.3 [LegacyNamespace]
WebIDL spec, §3.4.4 [LegacyNoInterfaceObject]
WebIDL spec, §3.4.5 [LegacyNullToEmpyString]
WebIDL spec, §3.4.6
PR mdn/content#28213[LegacyOverrideBuiltIns]
WebIDL spec, §3.4.7 [LegacyTreatNonObjectAsNull]
WebIDL spec, §3.4.8 [LegacyUnenumerableNamedProperties
WebIDL spec, §3.4.9 [LegacyUnforgeable]
WebIDL spec, §3.4.10 [LegacyWindowAlias]
WebIDL spec, §3.4.11 [Serializable]
HTML spec, $2.7.1[HTMLConstructor]
HTML spec, $3.2.3[CEReactions]
HTML spec There are many of these[Transferable]
HTML spec, $2.7.2[WebGLHandlesContextLoss]
setlike<…>
maplike<…>
sequence<…>
iterable<…>
record<…>
Promise<…>
(especially Promise<undefined>
)Array<…>
FrozenArray<…>
typedef
( … or … )
)any
getter
(named)getter
(unnamedstringifier
inherit
attributeCSSOMString
USVString
DOMString
ByteString
DOMHighResTimeStamp
DOMTimeStamp
callback
, how to document these?The discussion for iterable, maplike, setlike has been started here: https://github.com/orgs/mdn/discussions/707
Problem statement
In MDN Web API reference docs, we've been using WebIDL to derive rules for how we want to structure and make the API docs most consistent and useful for web developers.
For example, we said:
_static
suffix in the MDN page slug and in BCD paths.For certain WebIDL concepts, or annotations, we are less clear how to consistently document things. For example,
Proposed solutions
Provide MDN authors (and readers) a clear structure for Web API docs by agreeing on how and where to document aspects of Web APIs like maplikes, jsonifiers, (async) iterables etc.
Ideal outcome: Any WebIDL fragment can be taken and it is clear what it will mean in terms of structure and docs on MDN and in BCD. This will make the docs predictable and also it will be easier to generate docs from tooling with consistent structures.
Task list
A good starting point is https://github.com/mdn/browser-compat-data/issues/6367
Priority assessment
More information
Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.
In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs. For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/
More information is available at https://openwebdocs.org/. For questions, please reach out to florian@openwebdocs.org.