Documenting typedefs in Web API docs

[Elchi3]

Web APIs take or return certain types defined in WebIDL. How does MDN document them?

I'm working on Performance API docs and the type DOMHighResTimeStamp is quite an important concept there. However, it seems that typedefs aren't documented on their own page in the MDN Web/API/* reference anymore and so this page should rather be glossary page or so. I'm not yet quite clear where I should put it. See mdn/content#17096 as an example that creates a glossary entry and removes the API page. The browser-compat-data project doesn't include types anymore either, see mdn/browser-compat-data#9930 (that's why we have a broken compat table on DOMHighResTimeStamp).

I believe a lot types are documented inline (like MDN does for dictionaries). While that is good in may cases, it might not make sense in all cases. Let's explore WebIDL typedefs. I think there are a few different categories to talk about here:

Aliases

Very often types are used to create aliases (or groups of types) to indicate that two or more types can be used or will be returned. These groups are invisible to web developers. On MDN, we don't talk about these aliases. And I think it has been a good idea that BCD also removed these. We always list all specific real types instead. See for example https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createPattern where for the image parameter, all canvas images sources are listed and it's not written "CanvasImageSource" that wouldn't necessarily mean anything to a web developer. Examples of these kinds of typedefs:

• AlgorithmIdentifier: object or string
• ArrayBufferView: Int8Array or Int16Array or Int32Array or Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or BigInt64Array or BigUint64Array or Float32Array or Float64Array or DataView
• CanvasImageSource: HTMLOrSVGImageElement or HTMLVideoElement or HTMLCanvasElement or ImageBitmap or OffscreenCanvas or VideoFrame
• BinaryData: ArrayBuffer or ArrayBufferView
• BlobPart: BufferSource or Blob or USVString
• BodyInit: ReadableStream or XMLHttpRequestBodyInit
• BufferSource: ArrayBuffer or ArrayBufferView
• CryptoKeyID: SmallCryptoKeyID or bigint
• FileSystemWriteChunkType: BufferSource or Blob or USVString or WriteParams

Ordinary types with meaning

Some typedefs are ordinary types, however, they have special meaning and possibly constrains that are worth knowing. I believe that our current thinking is that these should be glossary pages? I think it would be nice to be consistent about them, either in the glossary or in a dedicated section on MDN that talks about them. I think the following typedefs fall into this category:

• DOMHighResTimeStamp
• DOMTimeStamp
• EpochTimeStamp
• Base64URLString
• BigInteger
• BluetoothCharacteristicUUID
• BluetoothDescriptorUUID
• BluetoothServiceUUID
• COSEAlgorithmIdentifier
• CSSColorAngle
• CSSColorNumber
• CSSColorPercent
• CSSColorRGBComp
• CSSKeywordish
• CSSNumberish
• CSSPerspectiveValue
• CSSStringSource
• CSSToken
• CSSUnparsedSegment
• GLbitfield
• GLboolean
• GLbyte
• GLclampf
• GLenum
• GLfloat
• GLint
• GLint64
• GLintptr
• GLshort
• GLsizei
• GLsizeiptr
• GLubyte
• GLuint
• GLuint64
• GLuint64EXT
• GLushort

Data structures

Some types seem to have have defined data structures. If they are simple (for example, an array of specific elements), it seems that we can document them inline without introducing the abstract typedef at all. If they are more complex (see eg. the Costraints typedefs) then I guess they ought to be explained somewhere somehow. There seems to be no guideline about this, though. Documenting them inline might lead to repeatedly explaining their complex structure. I think the following typedefs are examples:

• AttributeMatchList: record<DOMString, sequence<DOMString>>
• ClipboardItemData: Promise<(DOMString or Blob)>
• ClipboardItems: sequence<ClipboardItem>: array of ClipboardItem elements
• ConstrainBoolean: See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints (dictionary page!)
• ConstrainDOMString: See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints (dictionary page!)
• ConstrainDouble: See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints (dictionary page!)
• ConstrainPoint2D: See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints (dictionary page!)
• ConstrainULong: See https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints (dictionary page!)
• CookieList: sequence<CookieListItem>

Handlers

I think these typedefs are mostly functions and are used a lot (for all events for example). Might be worth have pages for these types? If so, where?

• EventHandler
• TimerHandler
• OnBeforeUnloadEventHandler
• OnErrorEventHandler

Other types (not yet sorted)

- Float32List - FormDataEntryValue - GPUBindingResource - GPUBufferDynamicOffset - GPUBufferUsageFlags - GPUColor - GPUColorWriteFlags - GPUComputePassTimestampWrites - GPUDepthBias - GPUExtent3D - GPUFlagsConstant - GPUIndex32 - GPUIntegerCoordinate - GPUMapModeFlags - GPUOrigin2D - GPUOrigin3D - GPUPipelineConstantValue - GPURenderPassTimestampWrites - GPUSampleMask - GPUShaderStageFlags - GPUSignedOffset32 - GPUSize32 - GPUSize64 - GPUStencilValue - GPUTextureUsageFlags - GeometryNode - HTMLOrSVGImageElement - HTMLOrSVGScriptElement - HTMLString - HashAlgorithmIdentifier - HeadersInit - ImageBitmapSource - ImageBufferSource - Int32List - LineAndPositionSetting - MLBufferView - MLGPUResource - MLNamedArrayBufferViews - MLNamedGPUResources - MLNamedOperands - MediaProvider - Megabit - MessageEventSource - Millisecond - NDEFMessageSource - NamedCurve - OffscreenRenderingContext - PasswordCredentialInit - PerformanceEntryList - ProfilerResource - PublicKeyCredentialJSON - PushMessageDataInit - RTCRtpTransform - ReadableStreamController - ReadableStreamReader - RenderingContext - ReportList - RequestInfo - RotationMatrixType - ScriptString - ScriptURLString - SmallCryptoKeyID - StartInDirectory - TexImageSource - TrustedType - URLPatternInput - UUID - Uint32List - UvmEntries - UvmEntry - VibratePattern - XMLHttpRequestBodyInit - XRWebGLRenderingContext

[hamishwillee]

My understanding is that the rule is that:

• dictionaries and typedefs are not and should not documented as though they were "code entities". Full stop.
• If the entity/concept is "concise" you would document in place where it is used - duplicating everywhere.
• If the entity/concept is significant and each instance will always be the same then you might document in one place and then link everywhere to that same place. Think the CSP origin docs.
• If the concept is signficant but can differ in each place, you still should document in each place. I say "should" because maintenance has to be a consideration. If you can do so "safely" you might have common docs in one place and "deltas" with a link where they are used.
• We wouldn't use glossary generally for language specific code concepts. For example DOMHighResTimeStamp is only interesting in a code context, and if you need to know the nuances, then you need to know it in the DOM context, alongside the DOM docs.

Looking at a couple of cases:

• EpochTimeStamp - I'm pretty sure this is the Unix epoch timestamp and normally I'd normally replace it with a glossary entry "Unix epoc timestamp" because that is a general concept.
  • There is a wrinkle here though that this is the entity that superseded DOMTimeStamp - and that can't necessarily just be removed.
• DOMTimeStamp - this one is hard to remove because according to the spec it is a general timestamp that has meaning in defined in other specs - it is generally a unix epoch timestamp, but it doesn't have to be.
• DOMHighResTimeStamp
  • would normally be done by documenting in each place it is used - you can see this in https://developer.mozilla.org/en-US/docs/Web/API/Event/timeStamp#reduced_time_precision.

In this case, if it were me I would be tempted to add a glossary for "Unix epoc time stamp" and perhaps have a guide topic "DOM timestamps" that captured DOMHighResTimeStamp.

If you keep DOMHighResTimeStamp IMO it can be cut back a bit IMO - too much information.

[wbamberg]

I don't have much to add to this.

We wouldn't use glossary generally for language specific code concepts

This is a really good point that's often ignored.

wrt the specific case: I think we should handle DOMHighResTimeStamp with a section on "timestamps in the Performance API", maybe in the Performance_API overview page or even as a separate guide page under Performance_API.

DOMTimeStamp - this one is hard to remove because according to the spec it is a general timestamp that has meaning in defined in other specs - it is generally a unix epoch timestamp, but it doesn't have to be.

This I don't understand though, I thought DOMTimeStamp was replaced with EpochTimeStamp (according to https://developer.mozilla.org/en-US/docs/Web/API/DOMTimeStamp, and also features like https://developer.mozilla.org/en-US/docs/Web/API/Notification/timestamp, which we document as using DOMTimeStamp, but the spec uses EpochTimeStamp: https://notifications.spec.whatwg.org/#timestamp).

(but I think we should discuss that case in mdn/content#17096.

[hamishwillee]

A section on the timestamp behaviour in performance API along with glossary topic for unix timestamps woud work well IFF DOMTimeStamp can be disposed of. I have responded re DOMTimeStamp in mdn/content#17096 (comment).

[Elchi3]

Thanks both! It seems like the answer is that we will use glossary entries to explain general concepts and sometimes have pages within an API section like "Performance_API/High-resolution_timestamps" or similar so that the typedef is explained close to the API defining it.

An alternative would be to document certain web platform types consistently somewhere, like "API/typdefs/DOMHighResTimeStamp" or similar, but it sounds like that's not desired and typedefs should always be treated like we treat dictionaries -- opaque to MDN readers.

[hamishwillee]

Yes.

but it sounds like that's not desired and typedefs should always be treated like we treat dictionaries -- opaque to MDN readers.

I think that's the "rule"; how hard we want to go with that would probably depend whether we find an exception where that is not workable.

[Rumyra]

Sounds like y'all have resolved this - I think the above sounds more than resonable 👍