BiDi docs: Update syntax blocks to include parameter examples#44402
BiDi docs: Update syntax blocks to include parameter examples#44402dipikabh wants to merge 1 commit into
Conversation
Preview URLs (13 pages)
Flaws (10)Note! 10 documents with no flaws that don't need to be listed. 🎉 Found an unexpected or unresolvable flaw? Please report it here. URL:
URL:
URL:
|
chrisdavidmills
left a comment
chrisdavidmills
left a comment
There was a problem hiding this comment.
Nice work, @dipikabh. This is really useful and helpful. I had a few comments.
|
|
||
| - [`acceptInsecureCerts`](/en-US/docs/Web/WebDriver/Reference/Capabilities/acceptInsecureCerts) {{optional_inline}} | ||
| - : A boolean that controls whether untrusted TLS certificates (for example, self-signed or expired) are accepted within this user context. When set, it overrides the [session-level](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new#acceptinsecurecerts) `acceptInsecureCerts` setting for this user context. | ||
| - `proxy` {{optional_inline}} |
There was a problem hiding this comment.
I'm not gonna block on this, but I am a little surprised that these object params don't have nested DLs explaining the properties that go inside each object, what they do, what values they can take, etc.
Is there a reason for this? Maybe something to think about for further enhancement later on.
| "method": "browser.setDownloadBehavior", | ||
| "params": { | ||
| "downloadBehavior": {} | ||
| "downloadBehavior": { |
There was a problem hiding this comment.
This seems a bit heavy-handed for a Syntax section, and it repeats much of what is shown in the Examples section. I would suggest:
- Cutting it down to two examples, one showing mandatory params, and one showing all the optional params too
- Adding the per-user context example to the Examples section.
| ## Syntax | ||
|
|
||
| ```json-nolint | ||
| /* Window */ |
There was a problem hiding this comment.
Again, seems a bit heavy-handed for a Syntax section. Same approach as I suggested for setDownloadBehavior?
| ## Syntax | ||
|
|
||
| ```json-nolint | ||
| /* Key action */ |
There was a problem hiding this comment.
Again, seems heavy-handed. Same approach as I suggested for setDownloadBehavior?
| "platformName": "mac", | ||
| "unhandledPromptBehavior": { | ||
| "default": "accept" | ||
| } |
There was a problem hiding this comment.
Feels like it should include some firstMatch examples too, although it might get a bit long. Does each object in the firstMatch array have to include all the same capabilities as the alwaysMatch object?
| @@ -12,10 +12,37 @@ The `session.subscribe` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modul | |||
| ## Syntax | |||
|
|
|||
| ```json-nolint | |||
There was a problem hiding this comment.
Again, feels heavy-handed. Same approach as suggested for setDownloadBehavior?
| To unsubscribe using subscription ID: | ||
|
|
||
| ```json-nolint | ||
| /* Using event name */ |
There was a problem hiding this comment.
Couple of thoughts:
- I think in this case, since you have to supply one of two choices, deviating from the usual mandatory/optional pattern is fine.
- Maybe swap the order of the two examples so they match the order in the Parameters section?
3 participants
Description
This is a follow-up to the feedback received in #44279 (comment).
Syntax blocks now show minimal (required set) and full (optional parameters) forms where applicable and also values for parameters instead of variables.
The approach here is based on the syntax pattern used in
browsingContext.getTreein PR 44279.Additionally,
In
browsingContext.getTree:json->json-nolintfor code blocks that have inline commentsIn
session.unsubscribe:Motivation
The "Syntax" block will now show meaningful usage information and allow readers to quickly grasp what's possible before they reach for the details in the "Parameters" section.