Skip to content

Commit

Permalink
docs: remove require, add example gno doc (#3576)
Browse files Browse the repository at this point in the history
This pull request is for :

- remove `require` statement from official documentation
[#3123](#3123)
- add an example that was `//TODO` in the `effective-gno / Documentation
is for users` section
  • Loading branch information
mous1985 authored Jan 23, 2025
1 parent 2ec6a15 commit 8851ff4
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 8 deletions.
52 changes: 51 additions & 1 deletion docs/concepts/effective-gno.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,57 @@ main purpose in Gno is for discoverability. This shift towards user-centric
documentation reflects the broader shift in Gno towards making code more
accessible and understandable for all users, not just developers.

TODO: `func ExampleXXX`.
Here's an example from [grc20](https://gno.land/p/demo/grc/grc20$source&file=types.gno)
to illustrate the concept:

```go
// Teller interface defines the methods that a GRC20 token must implement. It
// extends the TokenMetadata interface to include methods for managing token
// transfers, allowances, and querying balances.
//
// The Teller interface is designed to ensure that any token adhering to this
// standard provides a consistent API for interacting with fungible tokens.
type Teller interface {
exts.TokenMetadata

// Returns the amount of tokens in existence.
TotalSupply() uint64

// Returns the amount of tokens owned by `account`.
BalanceOf(account std.Address) uint64

// Moves `amount` tokens from the caller's account to `to`.
//
// Returns an error if the operation failed.
Transfer(to std.Address, amount uint64) error

// Returns the remaining number of tokens that `spender` will be
// allowed to spend on behalf of `owner` through {transferFrom}. This is
// zero by default.
//
// This value changes when {approve} or {transferFrom} are called.
Allowance(owner, spender std.Address) uint64

// Sets `amount` as the allowance of `spender` over the caller's tokens.
//
// Returns an error if the operation failed.
//
// IMPORTANT: Beware that changing an allowance with this method brings
// the risk that someone may use both the old and the new allowance by
// unfortunate transaction ordering. One possible solution to mitigate
// this race condition is to first reduce the spender's allowance to 0
// and set the desired value afterwards:
// https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
Approve(spender std.Address, amount uint64) error

// Moves `amount` tokens from `from` to `to` using the
// allowance mechanism. `amount` is then deducted from the caller's
// allowance.
//
// Returns an error if the operation failed.
TransferFrom(from, to std.Address, amount uint64) error
}
```

### Reflection is never clear

Expand Down
8 changes: 1 addition & 7 deletions docs/concepts/gno-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,20 +24,14 @@ The gno command-line tool provides several commands to work with the gno.mod fil

- **gno mod init**: small helper to initialize a new `gno.mod` file.
- **gno mod download**: downloads the dependencies specified in the gno.mod file. This command fetches the required dependencies from chain and ensures they are available for local testing and development.
- **gno mod tidy**: removes any unused dependency and adds any required but not yet listed in the file -- most of the maintenance you'll usually need to do!
- **gno mod why**: explains why the specified package or module is being kept by `gno mod tidy`.

## Sample `gno.mod` file

```
module gno.land/p/demo/sample
require (
gno.land/p/demo/avl v0.0.0-latest
gno.land/p/demo/testutils v0.0.0-latest
)
```

- **`module gno.land/p/demo/sample`**: specifies the package/realm import path.
- **`require` Block**: lists the required dependencies. Here using the latest available versions of "gno.land/p/demo/avl" and "gno.land/p/demo/testutils". These dependencies should be specified with the version "v0.0.0-latest" since on-chain packages currently do not support versioning.

0 comments on commit 8851ff4

Please sign in to comment.