From 8f065533dc3f529b79bd81abd3a4de5dfcc052b6 Mon Sep 17 00:00:00 2001
From: Luke Parker <lukeparker5132@gmail.com>
Date: Sun, 30 Oct 2022 12:27:16 -0400
Subject: [PATCH] Add documentation to public structs/functions in
 sc_tendermint

---
 substrate/tendermint/client/src/authority/mod.rs | 2 ++
 substrate/tendermint/client/src/block_import.rs  | 6 ++++++
 substrate/tendermint/client/src/lib.rs           | 2 ++
 substrate/tendermint/client/src/tendermint.rs    | 1 +
 substrate/tendermint/client/src/validators.rs    | 1 +
 5 files changed, 12 insertions(+)

diff --git a/substrate/tendermint/client/src/authority/mod.rs b/substrate/tendermint/client/src/authority/mod.rs
index 51d1c923..2280de78 100644
--- a/substrate/tendermint/client/src/authority/mod.rs
+++ b/substrate/tendermint/client/src/authority/mod.rs
@@ -62,12 +62,14 @@ struct ActiveAuthority<T: TendermintValidator> {
   announce: T::Network,
 }
 
+/// Tendermint Authority. Participates in the block proposal and voting process.
 pub struct TendermintAuthority<T: TendermintValidator> {
   import: TendermintImport<T>,
   active: Option<ActiveAuthority<T>>,
 }
 
 impl<T: TendermintValidator> TendermintAuthority<T> {
+  /// Create a new TendermintAuthority.
   pub fn new(import: TendermintImport<T>) -> Self {
     Self { import, active: None }
   }
diff --git a/substrate/tendermint/client/src/block_import.rs b/substrate/tendermint/client/src/block_import.rs
index 21ea4484..b5ebb3a4 100644
--- a/substrate/tendermint/client/src/block_import.rs
+++ b/substrate/tendermint/client/src/block_import.rs
@@ -67,6 +67,12 @@ where
   }
 }
 
+/// Tendermint's Select Chain, where the best chain is defined as the most recently finalized
+/// block.
+///
+/// leaves panics on call due to not being applicable under Tendermint. Any provided answer would
+/// have conflicts best left unraised.
+//
 // SelectChain, while provided by Substrate and part of PartialComponents, isn't used by Substrate
 // It's common between various block-production/finality crates, yet Substrate as a system doesn't
 // rely on it, which is good, because its definition is explicitly incompatible with Tendermint
diff --git a/substrate/tendermint/client/src/lib.rs b/substrate/tendermint/client/src/lib.rs
index bb370e49..7ec59218 100644
--- a/substrate/tendermint/client/src/lib.rs
+++ b/substrate/tendermint/client/src/lib.rs
@@ -102,6 +102,8 @@ pub trait TendermintValidator: TendermintClient {
 
 pub type TendermintImportQueue<Block, Transaction> = BasicQueue<Block, Transaction>;
 
+/// Create an import queue, additionally returning the Tendermint Import object iself, enabling
+/// creating an author later as well.
 pub fn import_queue<T: TendermintValidator>(
   spawner: &impl sp_core::traits::SpawnEssentialNamed,
   client: Arc<T::Client>,
diff --git a/substrate/tendermint/client/src/tendermint.rs b/substrate/tendermint/client/src/tendermint.rs
index d184d8fd..bfc8af39 100644
--- a/substrate/tendermint/client/src/tendermint.rs
+++ b/substrate/tendermint/client/src/tendermint.rs
@@ -22,6 +22,7 @@ use crate::{
   authority::TendermintAuthority,
 };
 
+/// Tendermint import handler.
 pub struct TendermintImport<T: TendermintValidator> {
   _ta: PhantomData<T>,
 
diff --git a/substrate/tendermint/client/src/validators.rs b/substrate/tendermint/client/src/validators.rs
index 177e7425..9a198390 100644
--- a/substrate/tendermint/client/src/validators.rs
+++ b/substrate/tendermint/client/src/validators.rs
@@ -79,6 +79,7 @@ impl<T: TendermintClient> Deref for Refresh<T> {
   }
 }
 
+/// Tendermint validators observer, providing data on the active validators.
 pub struct TendermintValidators<T: TendermintClient>(Refresh<T>);
 
 impl<T: TendermintClient> TendermintValidators<T> {