docs(examples): Create description for each crate in examples/* #3539
Conversation
mqxf
added
the
A1-inprogress
mqxf
added
A0-pleasereview
There was a problem hiding this comment.
as we now have documents for examples, we can build docs for them as well https://github.com/gear-tech/gear/blob/master/Makefile#L246
append --examples
There was a problem hiding this comment.
I believe the approach to docs should be different. Instead of writing literally every call in each function, you'd better give first some high-level, conceptual comments on purpose of that particular example, execution flow and how it reaches the purpose with that wasm. Entry points details about each procedure in them can be reduced.
Also to be clear, this is a general comment for all documented examples, not only "async" ones.
| @@ -16,6 +16,20 @@ | |||
| // You should have received a copy of the GNU General Public License | |||
| // along with this program. If not, see <https://www.gnu.org/licenses/>. | |||
|
|
|||
| //! This program demonstrates the use of async `init` entry point, as well as custom entry point | |||
There was a problem hiding this comment.
I would add some information about the execution. Docs should give some more description on async execution flow in this example.
| @@ -16,15 +16,17 @@ | |||
| // You should have received a copy of the GNU General Public License | |||
| // along with this program. If not, see <https://www.gnu.org/licenses/>. | |||
|
|
|||
| //! The program demonstrates asynchronous execution and | |||
| //! how to use macros `gstd::async_init`/`gstd::async_main`. | |||
| //! This program demonstrates asynchronous execution and how to use macros `gstd::async_init` and | |||
There was a problem hiding this comment.
please add a bit more info on the role of async here, as from description it seems same stuff can be done without async.
| @@ -16,6 +16,15 @@ | |||
| // You should have received a copy of the GNU General Public License | |||
| // along with this program. If not, see <https://www.gnu.org/licenses/>. | |||
|
|
|||
| //! This program demonstrates the use of an async recursive function using the [`async_recursion`] | |||
There was a problem hiding this comment.
Give more higher level explanations of the async execution flow.
examples/async-tester/src/wasm.rs
Outdated
| // You should have received a copy of the GNU General Public License | ||
| // along with this program. If not, see <https://www.gnu.org/licenses/>. | ||
|
|
||
| //! This program demonstrates the use of [`msg`] syscalls from an async environment. |
There was a problem hiding this comment.
| //! This program demonstrates the use of [`msg`] syscalls from an async environment. | |
| //! This program demonstrates the use of [`gstd::msg`] syscalls from an async environment. |
| //! [`Send`] uses the [`send_for_reply()`] syscall to send a message back to the source, containing | ||
| //! the `kind` in the payload. | ||
| //! | ||
| //! [`SendWithGas(gas)`] uses the [`send_with_gas_for_reply()`] syscall to send a message back to | ||
| //! the source, containing the `kind` in the payload, and `gas` as the gas limit. | ||
| //! | ||
| //! [`SendBytes`] uses the [`send_bytes_for_reply()`] syscall to send a message back to the source, | ||
| //! containing the `kind` encoded as bytes in the payload. | ||
| //! | ||
| //! [`SendBytesWithGas(gas)`] uses the [`send_bytes_with_gas_for_reply()`] syscall to send a message | ||
| //! back to the source, containing the `kind` encoded as bytes in the payload and `gas` as the gas | ||
| //! limit. | ||
| //! | ||
| //! [`SendCommit`] uses the [`MessageHandle`], pushing the `kind` encoded as bytes and using | ||
| //! [`commit_for_reply()`] to send the message back to the source. | ||
| //! | ||
| //! [`SendCommitWithGas(gas)`] uses the [`MessageHandle`], pushing the `kind` encoded as bytes and | ||
| //! using [`commit_with_gas_for_reply()`] to send the message back to the source with `gas` as the | ||
| //! gas limit. |
There was a problem hiding this comment.
You don't need to literally explain every step of the program. These steps are clear, btw. State main of this tester crate (look at the usage).
examples/async/src/wasm.rs
Outdated
| //! This program demonstrates use of an async `handle` entry point using the `gstd::async_main` | ||
| //! macro. | ||
| //! | ||
| //! `Init` method gets an address of a program in the payload, which should accept "PING" messages | ||
| //! and reply with "PONG". | ||
| //! | ||
| //! `Handle` is async and gets a [`Command`] in the payload, executes a certain action based on it, | ||
| //! and send a [`reply()`] with a payload containing the id of the current message. There are two commands | ||
| //! that can be executed: [`Common`] and [`Mutex`]. | ||
| //! | ||
| //! [`Common`] sends three async messages to the ping program, with the payload "PING", | ||
| //! awaits the reply and asserts that the reply is "PONG". | ||
| //! | ||
| //! [`Mutex`] asynchronously locks the mutex, awaiting it, sends a message back to the | ||
| //! source of the current message, containing the current message id in the payload, and then | ||
| //! it sends a ping message, awaiting the reply and asserting that the reply is "PONG". |
There was a problem hiding this comment.
it's not clear what this wasms does, what's the purpose of that.
techraed
added
A1-inprogress
|
Please re-open once work continued |
Resolves #2845.
Notes:
if_else#3487 is merged due to update to functionality.demo-constructor#3525.examples/*.@reviewer-or-team