Skip to content

Commit

Permalink
[documentation]: Actualise api_spec.md and fix doc comments (#3163)
Browse files Browse the repository at this point in the history 
* [docs]: actualise `api_spec`; fix links and format

Signed-off-by: Dmitry Balashov <[email protected]>

* [docs]: fix doc comments, use rustdoc references

Signed-off-by: Dmitry Balashov <[email protected]>

* [documentation]: use jsdoc notation; swap sections

Signed-off-by: Dmitry Balashov <[email protected]>

* Apply suggestions from code review

Co-authored-by: Aleksandr Petrosyan <[email protected]>
Signed-off-by: 0x009922 <[email protected]>

* [documentation]: apply code review suggestions

- clarify JSON response format for JSON5 snippet
- ~~"Update Configuration"~~ "Configuration"
- formatting chores

Signed-off-by: Dmitry Balashov <[email protected]>

* [docs]: put `allow(missing_docs)` instead of redundant docs

Signed-off-by: Dmitry Balashov <[email protected]>

* [docs]: make yet another rust doc link

Signed-off-by: Dmitry Balashov <[email protected]>

---------

Signed-off-by: Dmitry Balashov <[email protected]>
Signed-off-by: 0x009922 <[email protected]>
Co-authored-by: Aleksandr Petrosyan <[email protected]>
  • Loading branch information
@0x009922 @appetrosyan
0x009922 and appetrosyan authored Mar 17, 2023
1 parent 5310dd4 commit 726f5ea
Show file tree
Hide file tree
Showing 3 changed files with 168 additions and 133 deletions.
50 changes: 23 additions & 27 deletions core/src/block.rs
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
//! This module contains `Block` structures for each state, it's
//! This module contains [`Block`] structures for each state, it's
//! transitions, implementations and related traits
//! implementations. `Block`s are organised into a linear sequence
//! implementations. [`Block`]s are organised into a linear sequence
//! over time (also known as the block chain). A Block's life-cycle
//! starts from `PendingBlock`.
//! starts from [`PendingBlock`].
#![allow(
clippy::module_name_repetitions,
clippy::std_instead_of_core,
Expand Down Expand Up @@ -39,7 +39,7 @@ mod pending {
declare_versioned_with_scale!(VersionedPendingBlock 1..2, Debug, Clone, iroha_macro::FromVariant);

/// Transaction data is permanently recorded in files called
/// blocks. This is the first stage of a `Block`s life-cycle.
/// blocks. This is the first stage of a [`Block`]s life-cycle.
#[version_with_scale(n = 1, versioned = "VersionedPendingBlock")]
#[derive(Debug, Clone, Decode, Encode)]
pub struct PendingBlock {
Expand All @@ -52,7 +52,7 @@ mod pending {
}

impl PendingBlock {
/// Create a new `PendingBlock` from transactions.
/// Create a new [`PendingBlock`] from transactions.
#[inline]
pub fn new(
transactions: Vec<VersionedAcceptedTransaction>,
Expand Down Expand Up @@ -133,7 +133,7 @@ mod pending {
mod chained {
use super::*;

/// When `PendingBlock` chained with a blockchain it becomes `ChainedBlock`
/// When [`PendingBlock`] chained with a blockchain it becomes [`ChainedBlock`]
#[derive(Debug, Clone, Decode, Encode)]
pub struct ChainedBlock {
/// Block header
Expand Down Expand Up @@ -201,7 +201,7 @@ mod chained {
mod valid {
use super::*;

/// After full validation `ChainedBlock` can transform into `ValidBlock`.
/// After full validation [`ChainedBlock`] can transform into [`ValidBlock`].
#[derive(Debug, Clone)]
pub struct ValidBlock {
/// Block header
Expand All @@ -222,7 +222,7 @@ mod valid {
HashOf::new(&self.header).transmute()
}

/// Sign this block and get `SignedBlock`.
/// Sign this block and get [`SignedBlock`].
///
/// # Errors
/// Fails if signature generation fails
Expand All @@ -245,7 +245,7 @@ mod valid {
mod signed {
use super::*;

/// After receiving first signature, `ValidBlock` can transform into `SignedBlock`.
/// After receiving first signature, [`ValidBlock`] can transform into [`SignedBlock`].
#[derive(Debug, Clone)]
pub struct SignedBlock {
/// Block header
Expand All @@ -267,9 +267,8 @@ mod signed {
HashOf::new(&self.header).transmute()
}

/// Return signatures that are verified with the `hash` of this block, removing all other
/// signatures.
/// Return signatures that are verified with the `hash` of this block,
/// removing all other signatures.
#[inline]
pub fn retain_verified_signatures(&mut self) -> impl Iterator<Item = &SignatureOf<Self>> {
self.signatures.retain_verified_by_hash(self.hash())
Expand Down Expand Up @@ -331,7 +330,7 @@ mod signed {
Ok(self.commit_unchecked())
}

/// Add additional signatures for `SignedBlock`.
/// Add additional signatures for [`SignedBlock`].
///
/// # Errors
/// Fails if signature generation fails
Expand All @@ -344,7 +343,7 @@ mod signed {
})
}

/// Add additional signature for `SignedBlock`
/// Add additional signature for [`SignedBlock`]
///
/// # Errors
/// Fails if given signature doesn't match block hash
Expand All @@ -360,7 +359,7 @@ mod signed {
))
}

/// Create dummy `ValidBlock`. Used in tests
/// Create dummy [`ValidBlock`]. Used in tests
///
/// # Panics
/// If generating keys or block signing fails.
Expand Down Expand Up @@ -441,23 +440,23 @@ mod candidate {
}

impl VersionedCandidateBlock {
/// Convert from `&VersionedCandidateBlock` to V1 reference
#[allow(missing_docs)]
#[inline]
pub const fn as_v1(&self) -> &CandidateBlock {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `&mut VersionedCandidateBlock` to V1 mutable reference
#[allow(missing_docs)]
#[inline]
pub fn as_mut_v1(&mut self) -> &mut CandidateBlock {
match self {
Self::V1(v1) => v1,
}
}

/// Perform the conversion from `VersionedCandidateBlock` to V1
#[allow(missing_docs)]
#[inline]
pub fn into_v1(self) -> CandidateBlock {
match self {
Expand All @@ -472,14 +471,12 @@ mod candidate {
}

/// Calculate the hash of the current block.
#[inline]
pub fn hash(&self) -> HashOf<Self> {
self.as_v1().hash().transmute()
}

/// Return signatures that are verified with the `hash` of this block, removing all other signatures.
#[inline]
pub fn retain_verified_signatures(&mut self) -> impl Iterator<Item = &SignatureOf<Self>> {
self.as_mut_v1()
Expand Down Expand Up @@ -715,7 +712,7 @@ mod candidate_committed {
declare_versioned_with_scale!(VersionedCandidateCommittedBlock 1..2, Debug, Clone, iroha_macro::FromVariant);

/// Block state used to transfer accepted by consensus block through network to the other peers.
/// This block state is not entirely trusted and require hash revalidation to obtain `CommittedBlock`.
/// This block state is not entirely trusted and require hash revalidation to obtain [`CommittedBlock`].
#[version_with_scale(n = 1, versioned = "VersionedCandidateCommittedBlock")]
#[derive(Debug, Clone, Decode, Encode)]
pub struct CandidateCommittedBlock {
Expand All @@ -732,23 +729,23 @@ mod candidate_committed {
}

impl VersionedCandidateCommittedBlock {
/// Convert from `&VersionedCandidateCommittedBlock` to V1 reference
#[allow(missing_docs)]
#[inline]
pub const fn as_v1(&self) -> &CandidateCommittedBlock {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `&mut VersionedCandidateCommittedBlock` to V1 mutable reference
#[allow(missing_docs)]
#[inline]
pub fn as_mut_v1(&mut self) -> &mut CandidateCommittedBlock {
match self {
Self::V1(v1) => v1,
}
}

/// Performs the conversion from `VersionedCandidateCommittedBlock` to V1
#[allow(missing_docs)]
#[inline]
pub fn into_v1(self) -> CandidateCommittedBlock {
match self {
Expand All @@ -757,7 +754,7 @@ mod candidate_committed {
}

/// Calculate the hash of the current block.
/// `VersionedCandidateCommittedBlock` should have the same hash as `VersionedCommittedBlock`.
/// [`VersionedCandidateCommittedBlock`] should have the same hash as [`VersionedCommittedBlock`].
#[inline]
pub fn hash(&self) -> HashOf<Self> {
Expand Down Expand Up @@ -799,8 +796,7 @@ mod candidate_committed {

impl CandidateCommittedBlock {
/// Calculate the hash of the current block.
/// `CommitedBlock` should have the same hash as `ValidBlock`.
/// [`CommittedBlock`] should have the same hash as [`ValidBlock`].
#[inline]
pub fn hash(&self) -> HashOf<Self> {
HashOf::new(&self.header).transmute()
Expand Down
14 changes: 7 additions & 7 deletions data_model/src/events/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ pub mod pipeline;
pub mod time;

model! {
/// Event.
#[allow(missing_docs)]
#[derive(Debug, Clone, PartialEq, Eq, Hash, FromVariant, Decode, Encode, Deserialize, Serialize, IntoSchema)]
#[ffi_type]
pub enum Event {
Expand Down Expand Up @@ -116,21 +116,21 @@ pub mod stream {
declare_versioned_with_scale!(VersionedEventMessage 1..2, Debug, Clone, FromVariant, IntoSchema);

impl VersionedEventMessage {
/// Convert from `&VersionedEventPublisherMessage` to V1 reference
#[allow(missing_docs)]
pub const fn as_v1(&self) -> &EventMessage {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `&mut VersionedEventPublisherMessage` to V1 mutable reference
#[allow(missing_docs)]
pub fn as_mut_v1(&mut self) -> &mut EventMessage {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `VersionedEventPublisherMessage` to V1
#[allow(missing_docs)]
pub fn into_v1(self) -> EventMessage {
match self {
Self::V1(v1) => v1,
Expand All @@ -156,21 +156,21 @@ pub mod stream {
declare_versioned_with_scale!(VersionedEventSubscriptionRequest 1..2, Debug, Clone, FromVariant, IntoSchema);

impl VersionedEventSubscriptionRequest {
/// Convert from `&VersionedEventSubscriberMessage` to V1 reference
#[allow(missing_docs)]
pub const fn as_v1(&self) -> &EventSubscriptionRequest {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `&mut VersionedEventSubscriberMessage` to V1 mutable reference
#[allow(missing_docs)]
pub fn as_mut_v1(&mut self) -> &mut EventSubscriptionRequest {
match self {
Self::V1(v1) => v1,
}
}

/// Convert from `VersionedEventSubscriberMessage` to V1
#[allow(missing_docs)]
pub fn into_v1(self) -> EventSubscriptionRequest {
match self {
Self::V1(v1) => v1,
Expand Down
Loading

0 comments on commit 726f5ea

Please sign in to comment.