-
Notifications
You must be signed in to change notification settings - Fork 45
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Consider alternate styling/linking for method argument definitions #574
Comments
Note that the current style has been a compromise for not inducing too much change at a time during last year. I'd prefer alternative 1 (closest to prose) or 3 (concise, but the main text is in Description, which is less readable in the limited space), 2 (not preferred). |
I like option 1, but can we have the bold weight for identifiers while keeping the font size of the current form? Otherwise the words (graph, inputs, outputs) look awkwardly smaller from the rest of the text, which doesn't help readability. Option 2 is meh, preferring the bulleted list of 1 (though I can't articulate exactly why I prefer it 🤔, maybe just because I'm more used to it). Option 3 is quite okay too (can visually scan the field/parameter name and type really quickly), except that the nullable and optional columns squeeze the description text into narrow columns 🤏🔎👀 (same feedback as Zoltan). |
Yeah, it's just CSS - we can bump up the font size / override whatever's making it small. |
FYI, I've experimented more with (1) locally. A few notes for posterity:
|
It turns out you can do
... and both IDL methods get linked correctly. Tedious but doable. |
This can now be addressed via an additional lint rule. |
Also adds a lint rule to enforce that every argument given in IDL is linked to a prose definition for it, and a lint rule to look for argument definitions that don't match their methods. Fixes webmachinelearning#574
Method arguments are currently detailed with this markdown (using compute() as an example):
which renders as:
![](https://private-user-images.githubusercontent.com/771547/305544098-aeb6face-1976-46c3-87ff-41eb2d805c40.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ5NjkyMDYsIm5iZiI6MTcyNDk2ODkwNiwicGF0aCI6Ii83NzE1NDcvMzA1NTQ0MDk4LWFlYjZmYWNlLTE5NzYtNDZjMy04N2ZmLTQxZWIyZDgwNWM0MC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODI5JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgyOVQyMjAxNDZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0yY2JiOTBiZWZjMmVkNjE4M2FkYzNiNDcyYmNjNmVkYWE5NDM5MmRhMWI5ZjFmMjI4OTg5NWE1ZWZlNTcxNjE0JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.xXMUmVbztoWW5CBVWrVVXreLmBnAjxgpI5-odT_0QUY)
There are a few other forms used in other specs worth considering to improve maintainability.
Alternative 1: Make args into definitions
A minimal change makes the argument names become definitions which are get automatically linked, to help catch errors.
which renders as:
![](https://private-user-images.githubusercontent.com/771547/305548180-425ece34-f7ff-4248-a4d6-aa7ada0b7468.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ5NjkyMDYsIm5iZiI6MTcyNDk2ODkwNiwicGF0aCI6Ii83NzE1NDcvMzA1NTQ4MTgwLTQyNWVjZTM0LWY3ZmYtNDI0OC1hNGQ2LWFhN2FkYTBiNzQ2OC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODI5JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgyOVQyMjAxNDZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT03ZmE4ZWViYTRmZDkxODZiNzdmOWNjYjRmZmExNDlhNThmODYzMTRhZTlmYWUxOTNjMDFiMWEzNzI2NTY1Y2NhJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.9yoSbIl-Qd5KSup7zl45M8DTiBrK-V6_hyNnF4owR5Y)
Alternative 2: Style as definition list
Extending the above using a definition list, similar to what is currently done for dictionaries:
which renders as:
![](https://private-user-images.githubusercontent.com/771547/305544909-350f9c44-6bd9-4ad3-9abc-a298227cdcd9.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ5NjkyMDYsIm5iZiI6MTcyNDk2ODkwNiwicGF0aCI6Ii83NzE1NDcvMzA1NTQ0OTA5LTM1MGY5YzQ0LTZiZDktNGFkMy05YWJjLWEyOTgyMjdjZGNkOS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODI5JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgyOVQyMjAxNDZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0yYzQzN2Q0NWI4MmU5ZmE5YjA0YzM3Mjk5MmZiNjhkNTZmMmMxMjk3NDQ1ZDZlNjAxOTNjNWU2MzFkMjJmZTRlJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.7gUth2CU5TtPlRZR8G8-jJ25oAJQdcqry6QnD_NMp2g)
Alternative 3: Auto-generated table
This is a much more radical departure from what the spec has today. The spec source is extremely compact, which eases maintenance. Argument type, nullability, and optionality are filled in by Bikeshed automatically, reducing errors. On the flip side, I personally find the big table ugly.
which renders as:
![](https://private-user-images.githubusercontent.com/771547/305545690-fb73993e-8fec-49c3-aa7c-8a5435dc99ae.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ5NjkyMDYsIm5iZiI6MTcyNDk2ODkwNiwicGF0aCI6Ii83NzE1NDcvMzA1NTQ1NjkwLWZiNzM5OTNlLThmZWMtNDljMy1hYTdjLThhNTQzNWRjOTlhZS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODI5JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgyOVQyMjAxNDZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT05YzdhYTZhZGI4OWJlYmZhOTNjMWQxZWJlYjljZDI4MTExYWM0OTQ3YjJmZTI5OWEyNjI4MTUyM2NmNDQwMTk0JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.t1IwtoEEOorvM7k-abwbiHEurd-nEk_kcO17S5nemMg)
Note that for all of these the return value of the method is not handled.
The text was updated successfully, but these errors were encountered: