docs(Writing-Algorithms): fix promise/Infra tables against spec source
Verified against webidl/index.bs and infra/infra.bs source files:
Promises (WebIDL):
- Add [=a promise resolved with=] (was missing entirely, line 8617 in
webidl/index.bs) — this is as common as 'rejected with'
- Add [=promise/react=] and [=wait for all=]
- Clarify 'resolved with' vs 'resolve': one creates a new already-
resolved promise, the other settles an existing pending promise
- Fix ordering: 'resolved with' before 'rejected with' for symmetry
Infra maps/lists:
- Fix [=map/exists=] → [=map/exist=] (canonical lt in infra.bs is
'exist|contain', not 'exists|contains')
- Add linking text column showing exact lt values
- Split map and list operations into separate tables
- Add missing operations: set, remove, for each, is empty
docs(Writing-Algorithms): add common patterns section
Adds six new subsections based on gaps found during the Dahut API
live docs audit:
- [=this=] — how to reference the current object in algorithm steps
- Promise patterns — [=a new promise=], [=resolve=], [=reject=],
[=a promise rejected with=], fulfillment/rejection hooks
- Parallel algorithms — [=In parallel=], [=Queue a task=],
[=Fire an event=] with xref context (HTML spec)
- Dictionary/map access — |options|['key'] [=map/exists=],
Infra map/list operations table
- Abort handling — standard pattern for AbortSignal support
- Enum values in prose — data-dfn-type='enum-value' + data-dfn-for
Also adds links to Infra and WebIDL in Tips section.
docs: address reviewer feedback from Tab Atkins, annevk, Domenic personas
xref.md — add pipeline explanation showing how Reffy/WebRef/xref-service
works and what's required for a term to be findable (browser-specs,
data-export, Reffy crawl). Addresses Anne's 'the dependency is undocumented'.
a11y.md — add table of the four rules disabled by default
(color-contrast, landmark-one-main, landmark-unique, region) with
reasons. Addresses 'you never list the defaults'.
document.respec.md — add full error/warning object fields: title,
elements, details, cause (all from RespecError.toJSON()). Addresses
Domenic's 'partial docs are worse than no docs'.
preProcess.md / postProcess.md — replace toy examples with realistic
use cases (fetching external data and injecting dfns; validating output).
Addresses Domenic's 'the examples are toys'.
data-cite.md — add 'when to use data-cite' decision table; add
<dfn data-cite> re-export pattern. Addresses Domenic's 'you never
explain the affirmative use case'.
Writing-Algorithms.md (new) — algorithm prose conventions: ol.algorithm,
variable syntax, standard verbs (Let/Set/Return/Assert/For each),
Assert step handling, nested sub-steps, abstract operations, data-algorithm.
Addresses the missing 'how to write algorithm prose' gap flagged by
both annevk and Domenic. Added to sidebar.
_Sidebar.md — add Writing Algorithms to guides section.