Analyzing spec algorithms #663
Comments
This was referenced Aug 1, 2024
Closed
tidoust
added a commit
that referenced
this issue
Aug 26, 2024
Specs are sorted per URL in browser-specs. That order is not fantastic when preparing a human-readable report such as the one in: #663 The --sort option lets makes it possible to specify the order to follow at each level of the structured report: one of "default", "name" or "title". We may want to add additional possibilities over time.
tidoust
added a commit
that referenced
this issue
Aug 26, 2024
Specs are sorted per URL in browser-specs. That order is not fantastic when preparing a human-readable report such as the one in: #663 The --sort option lets makes it possible to specify the order to follow at each level of the structured report: one of "default", "name" or "title". We may want to add additional possibilities over time.
|
Status update:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Context: algorithms extraction
Reffy now extracts algorithms from specs, see algorithms extracts in Webref. Extraction is far from perfect (a number of limitations are noted as TODO comments in the extraction logic) but the results are still good enough to start analyzing potential problems in algorithms, see
study-algorithms.js.Also see @dontcallmedom's initial algorithms explorer based on the extracts.
Analysis: parallel steps that should call "queue a task"
First thing I analyzed are steps that run in parallel because I always forget the need to queue a task within parallel steps before resolving/rejecting a
Promiseor firing an event. @jyasskin noted the same problem back in 2022 in whatwg/html#8569. What's new here is that we can now compute that information automatically, giving us more weapons to play whack-a-mole.The results show that about 50% of the specs (56/113) that define algorithms with "in parallel" steps need fixing:
Specs with steps in parallel that miss a call to "queue a task" (56 specs)
To run the analysis and refresh the above results, retrieve Webref's latest crawl results data locally and run:
npx strudy inspect [pathto]/webref --what algorithms --structure type/spec --sort default/title > res.mdOn top of these problems (Edit: both examples have been fixed):
AbortControllerandAbortSignalobjects in the DOM spec seems wrong: step 3.2 should queue a task to resolvepwith amazingResult (but note step 2.3.2 seems correct, because abort steps run within a global task)(Edit: reported in Missing "queue a global task" to resolve Promise in abort example whatwg/dom#1300)
(Edit: reported in Example in parallelism section needs to "queue a task" to handle the promise whatwg/html#10535)
We could start reporting these problems to spec authors on a semi-automated basis (after review) as we do for broken links. Now, as noted by @jyasskin in whatwg/html#8569, "queue a task" means selecting a task source, which is also something that people get confused about (looking into it, I realize that I raised w3ctag/design-principles#38 on this topic back in 2016), and often choose to ignore.
Given the number of specs that get it wrong, two questions that I'm wondering about:
Further analyses
Additional analyses that could be done:
<dfn>, which should be easy to detect.Any other interesting or important analyses that could be worth looking into?
How to write/flag algorithms
More broadly speaking, algorithms are currently written with semi-formal structures. There are opportunities to converge on a more formal structure if that seems useful. Examples:
foo()method is invoked, run the following steps...", or algorithms sections where the sub-heading's title is the name of the algorithm.class="algorithm"attribute. This makes it harder to extract the relevant prose, algorithm name, and actual steps.On top of us raising issues afterwards, spec authoring tools could perhaps better guide spec authors at the authoring step. Additional classes could also help make algorithms visually more readable, as attempted with flowchart symbols in the algorithms explorer.
In any case, convergence would make it easier to extract the algorithms and run further analyses.
The text was updated successfully, but these errors were encountered: