docs(examples): Create description for each crate in examples/*

Makefile

@@ -249,7 +249,8 @@ doc:
 		-p gear-core -p gear-core-processor -p gear-lazy-pages -p gear-core-errors \
 		-p gmeta -p gstd -p gtest -p gear-wasm-builder -p gear-common \
 		-p pallet-gear -p pallet-gear-gas -p pallet-gear-messenger -p pallet-gear-payment \
-		-p pallet-gear-program -p pallet-gear-rpc-runtime-api -p pallet-gear-rpc -p pallet-gear-scheduler -p gsdk
+		-p pallet-gear-program -p pallet-gear-rpc-runtime-api -p pallet-gear-rpc -p pallet-gear-scheduler -p gsdk \
+		-p demo-*
 	@ cp -f images/logo.svg target/doc/rust-logo.svg
 
 .PHONY: kill-gear

examples/async-custom-entry/src/wasm.rs

@@ -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
+//! functions for `handle_reply` and `handle_signal`, using `gstd::async_init` and
+//! `gstd::async_main` macros.
+//!
+//! `Init` is async and saves the source of the message it receives.
+//!
+//! `Handle` is async and goes into an infinite loop.
+//!
+//! `HandleReply` and `HandleSignal` are custom functions, defined as parameters in the
+//! `gstd::async_init` macro. They send a message using [`send_bytes()`] containing their function name to the user saved
+//! by the `Init` method.
+//!
+//! [`send_bytes()`]: msg::send_bytes
+
 use gstd::{msg, ActorId};
 
 static mut USER: ActorId = ActorId::zero();

examples/async-init/src/wasm.rs

@@ -16,15 +16,18 @@
 // 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
+//! `gstd::async_main`. It uses async to be able to wait for replies to messages it sent during the execution without
+//! having to halt the execution and use `handle_reply`.
 //!
-//!  `Init` method gets three addresses, sends "PING" messages
-//! to them and waits for at least two replies with any payload ("approvals").
+//! `Init` is async and gets three addresses in the payload, sends "PING" messages to them and waits for
+//! at least two replies with any payload ("approvals").
 //!
-//! `Handle` processes only "PING" messages. When `handle` gets such message
-//! it sends empty requests to the three addresses and waits for just one approval.
-//! If an approval is obtained the method replies with "PONG".
+//! `Handle` is async and processes only "PING" messages. When `handle` gets such message it sends empty
+//! requests to the three addresses and waits for just one approval. If an approval is obtained the
+//! method sends a [`reply()`] with "PONG".
+//!
+//! [`reply()`]: msg::reply
 
 use crate::InputArgs;
 use futures::future;

examples/async-recursion/src/wasm.rs

@@ -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`]
+//! macro.
+//!
+//! `Init` method gets one address in the payload, which is saves.
+//!
+//! `Handle` is async and calls the recursive function with the payload as an i32 parameter `val`.
+//! The function then sends a message with payload "PING" and awaits reply, then calls itself with
+//! `val - reply.len()` while `val - reply.len() > 0`.
+
 use async_recursion::async_recursion;
 use gstd::{msg, prelude::*, ActorId};
 

examples/async-signal-entry/src/wasm.rs

@@ -16,6 +16,23 @@
 // 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 automatically generated `handle_signal` function when using
+//! `gstd::async_init` or `gstd::async_main`.
+//!
+//! `Init` is async and gets an [`InitAction`] in the payload, if the action is
+//! [`Panic`](InitAction::Panic), we send a message using [`send_for_reply()`] back to the source
+//! containing "init" as the payload, and then we [`panic!()`](core::panic), triggering a signal.
+//!
+//! `Handle` is async and calls [`send()`] a message back to the source containing "handle_signal"
+//! as the payload, then calls [`wait()`].
+//!
+//! The automatically generated `handle_signal` contains a call to [`gstd::handle_signal()`]
+//!
+//! [`send_for_reply()`]: msg::send_for_reply
+//! [`send()`]: msg::send
+//! [`wait()`]: exec::wait
+//! [`gstd::handle_signal()`]: gstd::handle_signal
+
 use crate::InitAction;
 use gstd::{exec, msg};
 

examples/async-tester/src/lib.rs

@@ -1,3 +1,21 @@
+// This file is part of Gear.
+
+// Copyright (C) 2022-2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 use parity_scale_codec::{Decode, Encode};
 

examples/async-tester/src/wasm.rs

@@ -1,3 +1,59 @@
+// This file is part of Gear.
+
+// Copyright (C) 2022-2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// 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 [`gstd::msg`] syscalls from an async environment.
+//!
+//! `Handle` is async and gets a [`Kind`] in the payload, executing a syscall based on the `Kind`,
+//! and sending a message back to the source with the payload "PONG".
+//!
+//! [`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.
+//!
+//! [`Send`]: Kind::Send
+//! [`SendWithGas(gas)`]: Kind::SendWithGas
+//! [`SendBytes`]: Kind::SendBytes
+//! [`SendBytesWithGas(gas)`]: Kind::SendBytesWithGas
+//! [`SendCommit`]: Kind::SendCommit
+//! [`SendCommitWithGas(gas)`]: Kind::SendCommitWithGas
+//! [`send_for_reply()`]: msg::send_for_reply
+//! [`send_with_gas_for_reply()`]: msg::send_with_gas_for_reply
+//! [`send_bytes_for_reply()`]: msg::send_bytes_for_reply
+//! [`send_bytes_with_gas_for_reply()`]: msg::send_bytes_with_gas_for_reply
+//! [`commit_for_reply()`]: MessageHandle::commit_for_reply
+//! [`commit_with_gas_for_reply()`]: MessageHandle::commit_with_gas_for_reply
+
 use crate::Kind;
 use gstd::{
     msg::{self, MessageHandle},

examples/async/src/wasm.rs

@@ -16,6 +16,27 @@
 // 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 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",
+//! asynchronously 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".
+//!
+//! [`Common`]: Command::Common
+//! [`Mutex`]: Command::Mutex
+//! [`reply()`]: msg::reply
+
 use crate::Command;
 use gstd::{msg, prelude::*, sync::Mutex, ActorId};
 

examples/autoreply/src/wasm.rs

@@ -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 receiving an autoreply after sending a message and creating a reply
+//! deposit. It uses a flag `RECEIVED_AUTO_REPLY` which is false by default.
+//!
+//! `Init` method gets an address of a program in the payload, which will be sending the autoreply,
+//! and saves it.
+//!
+//! `Handle` method sends the payload "Hi" to the saved address, as long as it is not zero. Then it
+//! creates a reply deposit with `1_000_000_000` gas, to handle the reply.
+//!
+//! `HandleReply` receives the reply and sets a flag `RECEIVED_AUTO_REPLY` to `true`.
+//!
+//! `State` is a custom function which is exported, and it replies with the current value of the
+//! flag `RECEIVED_AUTO_REPLY`.
+
 use gstd::{debug, exec, msg, prelude::*, ActorId};
 
 static mut DESTINATION: ActorId = ActorId::zero();

examples/calc-hash/in-one-block/src/wasm.rs

@@ -1,3 +1,29 @@
+// This file is part of Gear.
+
+// Copyright (C) 2021-2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// 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 runs a hashing computation in one execution.
+//!
+//! `Handle` method gets a [`Package`] in the payload, and repeatedly calculates a sha256 hash,
+//! until the [`Package`] is finished. Once it is done, a [`reply()`] is sent, containing the result in
+//! the payload.
+//!
+//! [`reply()`]: msg::reply
+
 use crate::Package;
 use gstd::msg;
 

examples/calc-hash/over-blocks/src/wasm.rs

@@ -1,3 +1,47 @@
+// This file is part of Gear.
+
+// Copyright (C) 2021-2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// 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 runs a hashing computation over several executions.
+//!
+//! `Init` method gets a u64 `threshold` in the payload, and saves it.
+//!
+//! `Handle` method gets a [`Method`] in the payload, and it executes some code based on the method.
+//!
+//! [`Start { expected, id, src }`] uses the given values to make a new [`Package`], saving it in
+//! a static `registry`, mapping the `id` to a [`Package`]. We check if the [`Package`] is finished,
+//! and if it is, we [`reply()`] with the result in the payload. Otherwise, we [`wait()`], halting execution.
+//!
+//! [`Refuel(id)`] creates a message which is sent to this program, with the payload being
+//! [`Calculate(id)`].
+//!
+//! [`Calculate(id)`] checks that it has been called from this program, as it is a private method.
+//! The [`Package`] is retrieved from the static `registry` based on the `id`. While we have more
+//! gas than the `threshold`, we calculate the [`Package`] until it is finished. If out gas goes
+//! below the `threshold`, the execution is halted. If the [`Package`] is finished, we [`wake()`] the
+//! original message which sent the [`Start { expected, id, src }`].
+//!
+//! [`Start { expected, id, src }`]: Method::Start
+//! [`Refuel(id)`]: Method::Refuel
+//! [`Calculate(id)`]: Method::Calculate
+//! [`wait()`]: exec::wait
+//! [`wake()`]: exec::wake
+//! [`reply()`]: msg::reply
+
 use crate::Method;
 use gstd::{exec, msg};
 use types::Package;

examples/calc-hash/src/lib.rs

@@ -1,3 +1,21 @@
+// This file is part of Gear.
+
+// Copyright (C) 2021-2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
 #![no_std]
 
 extern crate alloc;

examples/constructor/src/arg.rs

@@ -1,3 +1,21 @@
+// This file is part of Gear.
+
+// Copyright (C) 2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
 use alloc::{
     string::{String, ToString},
     vec::Vec,

examples/constructor/src/builder.rs

@@ -1,3 +1,21 @@
+// This file is part of Gear.
+
+// Copyright (C) 2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
 use crate::{Arg, Call};
 use alloc::{string::ToString, vec, vec::Vec};
 use core::{fmt::Debug, ops::Deref};

examples/constructor/src/call.rs

@@ -1,3 +1,21 @@
+// This file is part of Gear.
+
+// Copyright (C) 2023 Gear Technologies Inc.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
 use crate::Arg;
 use alloc::{string::String, vec::Vec};
 use parity_scale_codec::{Decode, Encode};