Add Format Guidebook #987
Add Format Guidebook #987
Conversation
miden-lib/Format_Guidebook.md
Outdated
| - The description of the list should have a colon at the end. | ||
| - Depending on what kind of sentences form a list, they should start with a capital letter and end\ | ||
| with a dot, or start with a lowercase letter and without dot at the end. | ||
| - List should use a `-` symbol in case of unordered list or arabic numerals for ordered ones (for\ |
There was a problem hiding this comment.
Here, and in other similar places, I would use the word character instead of symbol.
miden-lib/comment_format.md
Outdated
|
|
||
| ### Outputs | ||
|
|
||
| Outputs should show the final state of each container, used in the inputs, except for the advice map: almost always the final state of the advice map is unimportant, since it is always the same as at the beginning of the procedure execution (see the example in the `Formats` section below). |
There was a problem hiding this comment.
almost always the final state of the advice map is unimportant, since it is always the same as at the beginning of the procedure execution
Nit: It's not entirely clear to me whether the advice map is always the same or almost always. Maybe this sentence could clarify.
There was a problem hiding this comment.
We have some instructions which put some data to the advice map, and I thought that we never used them in the miden-base, but I was wrong. I'll rewrite this paragraph and update the code which uses these instructions.
miden-lib/comment_format.md
Outdated
| Example: | ||
|
|
||
| ```masm | ||
| #! Sets the code of the account the transaction is being executed against. | ||
| #! | ||
| #! Inputs: [CODE_COMMITMENT] | ||
| #! Outputs: [] | ||
| #! | ||
| #! Where: | ||
| #! - CODE_COMMITMENT is the hash of the code to set. | ||
| #! | ||
| #! Panics if: | ||
| #! - this procedure is executed on the account which type differs from the `basic mutable`. | ||
| #! | ||
| #! Invocation: exec | ||
| ``` |
There was a problem hiding this comment.
I think it would be great if this was a full example here that showcases most, or all possible cases, so it can serve as a great first reference to look at. And only if one can't figure out from that example what a comment should look like, we can use the reference level guide below.
So basically I would just extend the current example with
- every possible value type (a felt, a word, a
_ptr) in eitherInputsorOutputs. Inputsspecifying Operand Stack, Advice Stack and Advice map.
This small PR adds the Format Guidebook presented in the ABI PR to the
miden-libcrate.