-
Notifications
You must be signed in to change notification settings - Fork 11.2k
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
[docs] Fleshed out Move docs using sui-move CLI a bit more #563
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So helpful, thank you!!
represent different types of user-defined coins as Sui objects: | ||
|
||
``` rust | ||
struct Coin<phantom T> has key, store { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Coin
is somewhat of an unfortunate starting point because we have to explain both generics and phantom
off-the bat... No concrete suggestions for alternatives + totally ok going forward with this, just registering the thought.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was thinking of what the starting point could be that would still work with the wallet part that I already wrote, and also involved just looking at our framework code rather than starting with code writing. I agree that this is a little dense, but I could not come with something obviously better and at least Coin is a familiar concept.
doc/move.md
Outdated
`Coin`, its definition must include the `id` field of `VersionedID` | ||
type (which struct type defined in the ID | ||
[module](../sui_programmability/framework/sources/ID.move)), and must | ||
also have the `key` ability used to enforce existence of the `id` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
also have the `key` ability used to enforce existence of the `id` | |
also have the `key` ability (which allows the object to be persisted in Sui's global storage) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is store
ability for then?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have rewritten it according to the suggestion, and left out description of the store
ability, but I am still confused why we need store
then if we already have key
. I makes some sense to me in Diem Move and its docs, but if I remember correctly, we re-purpose the key
ability in Sui a bit - is it still about only being able to use store operations (e.g., transferring ownership from one address to another) if a struct has the key
ability but not if it only has store
ability?
|
||
- must be public | ||
- must have no return value | ||
- its parameters are ordered as follows: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CC @lxfind who has ideas about relaxing these rules (and we could perhaps avoid explaining them if that change will go in soon, or remember to update this doc later if not)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know we have been musing about it, but I figure I should record the current state of the world for now - I am pretty sure this is not going to be the only change to the docs we will have to make in the future.
doc/move.md
Outdated
Move), which makes certain parts of the original Move documentation | ||
not applicable to smart contract development in Sui. | ||
In Sui, Move is used to define, create and manage programmable Sui | ||
[objects](https://github.com/MystenLabs/fastnft/blob/main/doc/objects.md#objects) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can make this link relative and avoid the named anchor, like so:
(objects.md)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure thing! I think I just pasted int the URL without thinking here...
doc/move.md
Outdated
representing user-level assets. Sui imposes additional restrictions | ||
on the code that can be written in Move, effectively using a subset of | ||
Move (a.k.a. Sui Move), which makes certain parts of the original Move | ||
documentation not applicable to smart contract development in Sui. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It would be good to highlight what aspects of the central Move docs are inapplicable here if we don't describe in detail below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's a little tough to specify, and certainly creating an exhaustive list here would be difficult. The point of this statement is that it is best to simply follow this tutorial and relevant Move documentation links provided in the tutorial rather than diving into "general" Move docs. I added a sentence to this effect, but also an example of a difference between Sui Move and "standard" Move.
doc/move.md
Outdated
`Coin` struct instance parameter and returns it. Please note that the | ||
coin parameter is a read-only reference to the `Coin` struct instance, | ||
indicated by the `&` preceding the parameter type. Move's type system | ||
enforces an invariant that struct instances arguments passes by |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
arguments pass
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It was meant to be "passed"
coin parameter is a read-only reference to the `Coin` struct instance, | ||
indicated by the `&` preceding the parameter type. Move's type system | ||
enforces an invariant that struct instances arguments passes by | ||
read-only references (as opposed to mutable references) cannot be |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that cannot
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See above comment. The whole sentence now reads (with another small typo fix - "instance" instead of "instances"):
"Move's type system enforces an invariant that struct instance arguments passed by read-only references (as opposed to mutable references) cannot be modified in the body of a function (you can read more about Move references here)"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fantastic work, Adam! I pointed out a few issues and will do a more thorough edit myself once you have finished your set of changes. Thanks!
df2d343
to
0625719
Compare
Rewritten the Move-related docs describing how to write/test Move code with sui-move CLI to better match the overall structure of the docs.
I also fleshed out the doc a bit more, adding description of structs and documentation on how to write and build a simple module.