OWD project: Doc structures for WebIDL concepts

[Elchi3]

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:

• Interfaces always get a page and Interface members are subpages.
• We avoid documenting mixins or dictionaries
• Static API members get the _static suffix in the MDN page slug and in BCD paths.
• etc.

For certain WebIDL concepts, or annotations, we are less clear how to consistently document things. For example,

• Maplikes and setlikes
• stringifiers, jsonifiers
• (... and more)

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

• Investigate and list which sort of WebIDL concepts exist (use webref or similar)
• For each WebIDL concept, determine if we have agreement how to document it on MDN and how we record it in BCD.
• For each unclear concept, start a discussion and come to a rule.
• Update MDN and BCD per the new rules
• Update MDN meta docs
• Find a place for where WebIDL concepts are explained to web developers (consensus seems to not do this in the glossary)

A good starting point is mdn/browser-compat-data#6367

Priority assessment

• Effort: Unclear, initial research needed.
• Dependencies:
• Community enablement: Discussion will be in the open. Feedback will be welcome.
• Momentum:
• Enabling learners:
• Enabling professionals:
• Underrepresented topics / Ethical web:
• Operational necessities:
• Addressing needs of the web industry:

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.

[Josh-Cena]

See also mdn/content#7844, mdn/content#6891

[teoli2003]

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)

Extended attributes

• [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

Legacy extended attributes

• [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 Add prose and meta-docs for [LegacyNullToEmptyString] 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

Other extended attributes

• [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]

Special types

• setlike<…>
• maplike<…>
• sequence<…>
• iterable<…>
• record<…>
• Promise<…> (especially Promise<undefined>)
• Array<…>
• FrozenArray<…>
• typedef
• Pseudo-typedef (( … or … ))
• any

Special operations

• getter (named)
• getter (unnamed
• stringifier
• inherit attribute

Special typedefs

• CSSOMString
• USVString
• DOMString
• ByteString
• DOMHighResTimeStamp
• DOMTimeStamp

Others

• callback, how to document these?