Repository navigation
V3 usage interactions inline & more structure - #30
Conversation
Documentation previewLast published commit: dbe5b15 This URL updates after each successful publication. A newer commit may still be building or awaiting approval. The preview is removed when this PR closes. |
| "5": | ||
| 1: {} | ||
| 5: | ||
| presence: required |
There was a problem hiding this comment.
looks like a missed edit?
There was a problem hiding this comment.
I left required in for now
| presence: optional | ||
| description: Include a nonzero Message ID to correlate the reply. | ||
| "5": | ||
| 1: {} |
There was a problem hiding this comment.
what is the purpose of having the empty {}? what will it hold?
I had said I thought it should be headers: [1] (implied required) , optionalHeaders:[]
There was a problem hiding this comment.
[1,2,3] doesnt work as we want more fields
"22":
presence: required
value: 2
| "6": {presence: optional} | ||
| "7": {presence: optional} | ||
| "10": {presence: optional} | ||
| 1: {} |
| request: | ||
| title: SET request | ||
| description: Use writable control fields, not the read-only GPS status field. | ||
| description: >- |
There was a problem hiding this comment.
i'm really confused why this is better than the per field descriptions we had beore
|
@addshore I'm stopping reviewing because it seems theres loads of unintentional changes? or I'm missing the point.. 100% this is worse that what we currently have IMO with no clear benefit? or maybe you're looking at something in particular? |
| "22": | ||
| 22: | ||
| presence: required | ||
| maxBytes: 1 |
There was a problem hiding this comment.
maxBytes: 1 shouldnt be here
|
As discussed: I'm awaiting a "reason for doing all this" - specifically why these changes are necessary and why this particular design has been chosen. In my view, we should be handling this with easier to read & maintain yaml, that matches how the code is written, rather than trying to cover every possibility. Personally I would see this as a combination of conventions and additional fields. Like we could have methods:
I'm not advocating for this format as is: just providing an example for what would make a lot more sense to me: IMO we need to collect the requirements to make a more informed / better planned decision |
Added clarification on request headers and message ID correlation.
Start the new iteration from current main while retaining this PR's existing history. Keep wire definitions, method maps and captured examples unchanged, and add named references with independent interaction revisions. Reuse existing exchange metadata through a validated resolver and retain existing documentation panels and anchors. Validate with 309 tests, the Next build and desktop/mobile interaction-link checks.
970927a to
5745361
Compare
| 1: | ||
| presence: required | ||
| 2: | ||
| presence: omitted |
There was a problem hiding this comment.
now I understand presence.. still wondering what "optional" means
|
@addshore added a few comments, wouldn't mind understanding a bit more of the design decisions |
| id: gsmControl | ||
| description: >- | ||
| GET returns GSM state directly. Successful SET operations return an ACK only when the request | ||
| includes a nonzero Message ID. |
There was a problem hiding this comment.
only when the request
includes a nonzero Message ID.
This is part of https://docs-next.lightbug.io/devices/api/protocol/responses not something that should be documented or written about in here
| name: GSM Control | ||
| id: gsmControl | ||
| description: >- | ||
| GET returns GSM state directly. Successful SET operations return an ACK only when the request |
There was a problem hiding this comment.
"GET returns GSM state directly. Successful SET operations"
This should be in the usage pattern descriptions if it even makes sense.
The description at this level should be about what GSM control means and does at a high level.
| @@ -1257,6 +1260,73 @@ messages: | |||
| methods: | |||
There was a problem hiding this comment.
In the future, i expect we can deduce all possible methods based on the interactions that are defined.
Or maybe now
| 3: {presence: ignored} | ||
| 4: {presence: ignored} | ||
| 5: {presence: omitted} | ||
| response: &gsmControlAck |
| method: GET | ||
| title: Read GSM state | ||
| versions: | ||
| 1: |
There was a problem hiding this comment.
Do we have to specify version 1,
When there is only 1 version?
| "0": Version 1 (also the omitted/malformed-width fallback) | ||
| "1": Version 1 | ||
| '0': Version 1 (also the omitted/malformed-width fallback) | ||
| '1': Version 1 |
There was a problem hiding this comment.
why '1': Version 1
Why not 1: Version 1
| description: >- | ||
| A successful GET returns this MT58 payload. An unsuccessful request returns | ||
| MT5 (ACK) with Status instead. | ||
| description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) |
There was a problem hiding this comment.
I wonder if in the docs actually view, we could auto turn things like MT58 literal in text into a clickable component thing
The intention here is to allow us to have more structure, rather than needing to just use descriptions etc to explain things, and also then feed into better auto generated documentation.
We are starting wtih this format in the docs repo, this is the 2nd iteration, and now we need to sync it back out into other places.