[documentation]: Review punctuation (#2872)

Co-authored-by: Aleksandr Petrosyan <a-p-petrosyan@yandex.ru>
Signed-off-by: Ekaterina Mekhnetsova <mekkatya@gmail.com>

CHANGELOG.rst

@@ -33,7 +33,7 @@ Features
 - hyperledger#1998 Add filters to queries.
 - hyperledger#2276 Include current Block hash into BlockHeaderValue.
 - hyperledger#2161 Handle id and shared FFI fns.
-  * add handle id and implement FFI equivalents of shared traits - Clone,Eq,Ord
+  * add handle id and implement FFI equivalents of shared traits (Clone, Eq, Ord)
 - hyperledger#1638 `configuration` return doc subtree.
 - hyperledger#2132 Add `endpointN` proc macro.
 - hyperledger#2257 Revoke<Role> emits RoleRevoked event.
@@ -101,13 +101,13 @@ Features
 - hyperledger#1172 Implement instruction events.
 - hyperledger#1734 Validate `Name` to exclude whitespaces.
 - hyperledger#1144 Add metadata nesting.
-- #1210 Block streaming - server side.
+- #1210 Block streaming (server side).
 - hyperledger#1331 Implement more `Prometheus` metrics.
 - hyperledger#1689 Fix feature dependencies. #1261: Add cargo bloat.
 - hyperledger#1675 use type instead of wrapper struct for versioned items.
 - hyperledger#1643 Wait for peers to commit genesis in tests.
 - hyperledger#1678 `try_allocate`
-- hyperledger#1216 Add Prometheus endpoint. #1216 - initial implementation of metrics endpoint.
+- hyperledger#1216 Add Prometheus endpoint. #1216: initial implementation of metrics endpoint.
 - hyperledger#1238 Run-time log-level updates. Created basic `connection` entrypoint-based reloading.
 - hyperledger#1652 PR Title Formatting.
 - Add the number of connected peers to `Status`
@@ -411,7 +411,7 @@ Tests
 - hyperledger#2272 Add tests for 'FindAssetDefinitionById' query.
 - Add `roles` integration tests.
 - Standardise ui tests format, move derive ui tests to derive crates.
-- Fix mock tests - futures unordered bug.
+- Fix mock tests (futures unordered bug).
 - Removed the DSL crate & moved tests to `data_model`
 - Ensure that unstable network tests pass for valid code.
 - Added tests to iroha_p2p.
@@ -520,7 +520,7 @@ Other
   1. Unsubscribe from broker on actor stop
   2. Support multiple subscriptions from the same actor type (previously a TODO)
   3. Fix a bug where broker always put self as an actor id.
-- Broker bug - test showcase.
+- Broker bug (test showcase).
 - Add derives for data model.
 - Remove rwlock from torii.
 - OOB Query Permission Checks.
@@ -800,7 +800,7 @@ Other
 - Prepare crates for publishing.
 - Minimum votes logic inside NetworkTopology.
 - TransactionReceipt validation refactoring.
-- OnWorldStateViewChange trigger change - IrohaQuery instead of
+- OnWorldStateViewChange trigger change: IrohaQuery instead of
   Instruction.
 - Separate construction from initialization in NetworkTopology.
 - Add Iroha Special Instructions related to Iroha events.
@@ -866,7 +866,7 @@ Other
 - Fix bug in Request deserialization.
 - Implementation of Iroha signature.
 - Blockchain entity was removed to clean up codebase.
-- Changes in Transactions API - better creation and work with requests.
+- Changes in Transactions API: better creation and work with requests.
 - Fix the bug that would create blocks with empty vector of transaction
 - Forward pending transactions.
 - Fix bug with missing byte in u128 scale encoded TCP packet.

cli/src/lib.rs

@@ -43,7 +43,8 @@ pub mod samples;
 mod stream;
 pub mod torii;
 
-/// Arguments for Iroha2 - usually parsed from cli.
+/// Arguments for Iroha2.
+/// Configuration for arguments is parsed from environment variables and then the appropriate object is constructed.
 #[derive(Debug)]
 pub struct Arguments {
     /// Set this flag on the peer that should submit genesis on the network initial start.
@@ -75,7 +76,7 @@ pub struct Iroha {
     pub queue: Arc<Queue>,
     /// Sumeragi consensus
     pub sumeragi: Arc<Sumeragi>,
-    /// Kura - block storage
+    /// Kura — block storage
     pub kura: Arc<Kura>,
     /// Block synchronization actor
     pub block_sync: AlwaysAddr<BlockSynchronizer>,

client/src/http.rs

@@ -11,7 +11,7 @@ pub use http::{Method, Response, StatusCode};
 /// The order of builder methods invocation is not strict. There is no guarantee that builder user calls
 /// all methods. Only [`RequestBuilder::new`] is the required one.
 pub trait RequestBuilder {
-    /// Entrypoint - create a new builder with specified method and URL.
+    /// Create a new builder with specified method and URL. Entrypoint for most client operations.
     #[must_use]
     fn new(method: Method, url: impl AsRef<str>) -> Self;
 
@@ -76,11 +76,11 @@ pub mod ws {
     ///
     /// Flow consists of the following:
     ///
-    /// 1. **Init stage** - establish `WebSocket` connection with Iroha
-    /// 2. **Handshake stage** - send a "subscription" message to Iroha and ensure that the next message from Iroha
+    /// 1. **Init stage**: establish `WebSocket` connection with Iroha
+    /// 2. **Handshake stage**: send a "subscription" message to Iroha and ensure that the next message from Iroha
     ///     is a "subscription accepted" message
-    /// 3. **Events stage** - wait for messages from Iroha. For each message, decode *some event* from it
-    ///     and send back *some "received"* mesage
+    /// 3. **Events stage**: wait for messages from Iroha. For each message, decode *some event* from it
+    ///     and send back *some "received"* message
     ///
     ///
     ///

core/src/block.rs

@@ -39,7 +39,7 @@ pub const DEFAULT_CONSENSUS_ESTIMATION_MS: u64 =
     DEFAULT_BLOCK_TIME_MS + (DEFAULT_COMMIT_TIME_LIMIT_MS / 2);
 
 /// The chain of the previous block hash. If there is no previous
-/// block - the blockchain is empty.
+/// block, the blockchain is empty.
 #[derive(Debug, Clone, Copy)]
 pub struct EmptyChainHash<T>(PhantomData<T>);
 

core/src/lib.rs

@@ -1,4 +1,4 @@
-//! Iroha - A simple, enterprise-grade decentralized ledger.
+//! Iroha — A simple, enterprise-grade decentralized ledger.
 
 pub mod block;
 pub mod block_sync;
@@ -33,16 +33,16 @@ pub type IrohaNetwork = iroha_p2p::Network<NetworkMessage>;
 /// Ids of peers.
 pub type PeersIds = DashSet<<Peer as Identifiable>::Id>;
 
-/// Provides an API to work with collection of key([`DomainId`]) - value([`Domain`]) pairs.
+/// API to work with collections of [`DomainId`] : [`Domain`] mappings.
 pub type DomainsMap = DashMap<<Domain as Identifiable>::Id, Domain>;
 
-/// `RolesMap` provides an API to work with a collection of key(`RoleId`) - value(`Role`) pairs.
+/// API to work with a collections of [`RoleId`]: [`Role`] mappings.
 pub type RolesMap = DashMap<<Role as Identifiable>::Id, Role>;
 
-/// `PermissionTokensMap` provides an API to work with a collection of key(`AccountId`) - value(`Set<PermissionToken>`) pairs.
+/// API to work with a collections of [`AccountId`] [`Permissions`] mappings.
 pub type PermissionTokensMap = DashMap<<Account as Identifiable>::Id, Permissions>;
 
-/// `PermissionTokenDefinitionsMap` provides an API to work with a collection of key(`PermissionTokenDefinitionId`) - value(`PermissionTokenDefinition`) pairs.
+/// API to work with a collections of [`PermissionTokenDefinitionId`] : [`PermissionTokenDefinition`] mappings.
 pub type PermissionTokenDefinitionsMap =
     DashMap<<PermissionTokenDefinition as Identifiable>::Id, PermissionTokenDefinition>;
 

core/src/smartcontracts/isi/domain.rs

@@ -129,7 +129,7 @@ pub mod isi {
                     for key_id in keys {
                         wsv.modify_account(account.id(), |account_mut| {
                             if account_mut.remove_asset(&key_id).is_none() {
-                                error!(%key_id, "asset not found - this is a bug");
+                                error!(%key_id, "asset not found. This is a bug");
                             }
 
                             Ok(AccountEvent::Asset(AssetEvent::Deleted(key_id)))

core/src/smartcontracts/isi/world.rs

@@ -278,7 +278,7 @@ pub mod isi {
                     })
                     .into())
                 } else {
-                    error!(%role_id, "role not found - this is a bug");
+                    error!(%role_id, "role not found. This is a bug");
                     Err(FindError::Role(role_id.clone()).into())
                 }
             })?;
@@ -312,7 +312,7 @@ pub mod isi {
                 wsv.modify_account(&account_id, |account| {
                     let id = account.id();
                     if !wsv.remove_account_permission(id, &token) {
-                        error!(%token, "token not found - this is a bug");
+                        error!(%token, "token not found. This is a bug");
                     }
 
                     Ok(AccountEvent::PermissionRemoved(id.clone()))

core/src/sumeragi/network_topology.rs

@@ -1,4 +1,4 @@
-//! Structs related to topology of the network - order and predefined roles of peers.
+//! Structures formalising the peer topology (e.g. which peers have which predefined roles).
 #![allow(
     clippy::new_without_default,
     clippy::std_instead_of_core,
@@ -92,13 +92,13 @@ impl GenesisBuilder {
         self
     }
 
-    /// Set a - validators and leader and proxy tail.
+    /// Set a — validators and leader and proxy tail.
     pub fn with_set_a(mut self, peers: HashSet<PeerId>) -> Self {
         self.set_a = Some(peers);
         self
     }
 
-    /// Set b - observing peers
+    /// Set b — observing peers
     pub fn with_set_b(mut self, peers: HashSet<PeerId>) -> Self {
         self.set_b = Some(peers);
         self
@@ -197,7 +197,7 @@ impl Builder {
     }
 }
 
-/// Network topology - order of peers that defines their roles in this round.
+/// The ordering of the peers which defines their roles in the current round of consensus.
 #[derive(Clone, Debug, Encode, Decode, IntoSchema, Serialize)]
 pub struct Topology {
     /// Current order of peers. The roles of peers are defined based on this order.
@@ -231,7 +231,7 @@ impl Topology {
             .expect("Topology was invalid.");
     }
 
-    /// Apply a view change - change topology in case there were faults in the consensus round.
+    /// Apply a `view change`, i.e. change the topology in case there were faults in the consensus round.
     #[allow(clippy::expect_used)]
     pub fn rebuild_with_new_view_change_count(&mut self, view_change_count: u64) {
         *self = self.clone().into_builder().build(view_change_count).expect(

core/src/sumeragi/view_change.rs

@@ -38,7 +38,7 @@ impl Proof {
     }
 
     /// Sign this message with the peer's public and private key.
-    /// This way peers vote for changing the view - changing the roles of peers.
+    /// This way peers vote for changing the view (changing the roles of peers).
     ///
     /// # Errors
     /// Can fail during creation of signature

core/src/wsv.rs

@@ -1,4 +1,4 @@
-//! This module provides the [`WorldStateView`] - in-memory representations of the current blockchain
+//! This module provides the [`WorldStateView`] — an in-memory representation of the current blockchain
 //! state.
 #![allow(
     clippy::new_without_default,
@@ -85,7 +85,7 @@ impl World {
 /// Current state of the blockchain aligned with `Iroha` module.
 #[derive(Debug)]
 pub struct WorldStateView {
-    /// The world - contains `domains`, `triggers`, etc..
+    /// The world. Contains `domains`, `triggers`, `roles` and other data representing the current state of the blockchain.
     pub world: World,
     /// Configuration of World State View.
     pub config: Configuration,

data_model/src/account.rs

@@ -37,8 +37,7 @@ use crate::{
     HasMetadata, Identifiable, Name, ParseError, PublicKey, Registered,
 };
 
-/// `AccountsMap` provides an API to work with collection of key (`Id`) - value
-/// (`Account`) pairs.
+/// API to work with collections of [`Id`] : [`Account`] mappings.
 pub type AccountsMap = btree_map::BTreeMap<<Account as Identifiable>::Id, Account>;
 
 // The size of the array must be fixed. If we use more than `1` we

data_model/src/asset.rs

@@ -25,12 +25,11 @@ use crate::{
     Identifiable, Name, ParseError, Registered, TryAsMut, TryAsRef, Value,
 };
 
-/// [`AssetsMap`] provides an API to work with collection of key ([`Id`]) - value
-/// ([`Asset`]) pairs.
+/// API to work with collections of [`Id`] : [`Asset`] mappings.
 pub type AssetsMap = btree_map::BTreeMap<<Asset as Identifiable>::Id, Asset>;
 
-/// [`AssetDefinitionsMap`] provides an API to work with collection of key ([`DefinitionId`]) - value
-/// (`AssetDefinition`) pairs.
+/// [`AssetDefinitionsMap`] provides an API to work with collection of key([`DefinitionId`])-value(`AssetDefinition`)
+/// pairs.
 pub type AssetDefinitionsMap =
     btree_map::BTreeMap<<AssetDefinition as Identifiable>::Id, AssetDefinitionEntry>;
 

docs/source/guides/actor.md

@@ -6,7 +6,7 @@ If you want to get a feel of the actor model a good way to start will be to read
 
 ## Properties
 
-- Everything is an actor (no main function in erlang or elixir - just start an actor)
+- Everything is an actor (no main function in erlang or elixir, just start an actor)
 - An actor receives and reacts in certain ways to messages:
   + Send messages to other actors
   + Create new actors
@@ -172,9 +172,9 @@ Actor1(broker).start().await;
 
 Via `notify_*` family functions for actors:
 
-- `notify` - send message once in some time
-- `notify_every` - sends message every duration time. Basically timer, from which you can't unsubscribe :)
-- `notify_with` - sinks stream into an actor
+- `notify` sends message once in some time
+- `notify_every` sends message every duration time. Basically timer, from which you can't unsubscribe :)
+- `notify_with` sinks stream into an actor
 
 ## Read more
 

docs/source/guides/develop-iroha-module.md

@@ -40,7 +40,7 @@ All public entites of your module should be documented as well. But first, let's
 
 ### 3. Write your logic
 
-The development of a new Iroha Module has a goal - to bring new functionality to Iroha.
+The development of a new Iroha Module has a goal of bringing new functionality to Iroha.
 So based on the goal and requirements, you have you will introduce new entities and place them inside newly created module.
 
 Let's specify particular categories of such entities and look how they can be implemented according to Iroha best practices.
@@ -125,9 +125,9 @@ And see what it does to register a new Bridge:
 
 We will not discuss Bridge-related terminology here – the thing we want to look at is how we can compose these steps into one new Iroha Special Instruction.
 
-As you can see, we have `Instruction::If(...)` here - it's [the utility Iroha Special Instruction](references/glossary#utility-iroha-special-instruction).
-It takes three arguments - `condition`, `instruction_to_do_if_true`, `instruction_to_do_if_false_or_nothing`.
-By this instruction we've made the first step of our algorithm - run a check and terminated execution if there is no Owner's Account.
+As you can see, we have `Instruction::If(...)` here. It's [the utility Iroha Special Instruction](references/glossary#utility-iroha-special-instruction).
+It takes three arguments: `condition`, `instruction_to_do_if_true`, `instruction_to_do_if_false_or_nothing`.
+By this instruction we've made the first step of our algorithm: run a check and terminate execution if there is no Owner's Account.
 Inside `condition` we placed `Instruction::ExecuteQuery(...)` which fails if [Iroha Query](references/glossary#iroha-query) fails.
 
 If the first step succeeds, we should move forward and execute sequence of the following steps.