Skip to content
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

Merged
merged 4 commits into from
Feb 25, 2022

Conversation

awelc
Copy link
Contributor

@awelc awelc commented Feb 25, 2022

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.

@awelc awelc self-assigned this Feb 25, 2022
@awelc awelc linked an issue Feb 25, 2022 that may be closed by this pull request
Copy link
Collaborator

@sblackshear sblackshear left a 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!!

doc/move.md Outdated Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
represent different types of user-defined coins as Sui objects:

``` rust
struct Coin<phantom T> has key, store {
Copy link
Collaborator

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.

Copy link
Contributor Author

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 Show resolved Hide resolved
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`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)

Copy link
Contributor Author

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?

Copy link
Contributor Author

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?

doc/move.md Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved

- must be public
- must have no return value
- its parameters are ordered as follows:
Copy link
Collaborator

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)

Copy link
Contributor Author

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 Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
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)
Copy link
Contributor

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)

Copy link
Contributor Author

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.
Copy link
Contributor

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.

Copy link
Contributor Author

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 Show resolved Hide resolved
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arguments pass

Copy link
Contributor Author

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that cannot

Copy link
Contributor Author

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)"

doc/move.md Outdated Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
doc/move.md Outdated Show resolved Hide resolved
Copy link
Contributor

@Clay-Mysten Clay-Mysten left a 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!

@awelc awelc merged commit 731fa7f into main Feb 25, 2022
@awelc awelc deleted the aw/move-docs-1 branch February 25, 2022 22:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[CLI] Developer docs - smart contracts with sui-move CLI
3 participants