Merge #4904

4904: Enable missing docs warning on EE and storage crates (#4106) r=EdHastingsCasperAssociation a=EdHastingsCasperAssociation

#4106 
As per title.

Co-authored-by: Ed Hastings <[email protected]>

execution_engine/src/lib.rs

@@ -12,6 +12,7 @@
  trivial_numeric_casts,
  unused_qualifications
 )]
+#![warn(missing_docs)]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 pub mod engine_state;

execution_engine/src/runtime/mint_internal.rs

@@ -64,7 +64,7 @@ where
  .read_addressable_entity_by_account_hash(account_hash)
  .map_err(|err| {
  error!(%err, "error reading addressable entity by account hash");
- ProviderError::AddressableEntityByAccountHash(account_hash)
+ ProviderError::AccountHash(account_hash)
  })
  }
 

execution_engine/src/runtime_context/mod.rs

@@ -1233,7 +1233,7 @@ where
  ) -> Result<Contract, ExecError> {
  self.tracking_copy
  .borrow_mut()
- .get_legacy_contract(legacy_contract)
+ .get_contract(legacy_contract)
  .map_err(Into::into)
  }
 

execution_engine_testing/test_support/src/wasm_test_builder.rs

@@ -1926,7 +1926,7 @@ where
  let req = TrieRequest::new(state_hash, None);
  self.data_access_layer()
  .trie(req)
- .into_legacy()
+ .into_raw()
  .unwrap()
  .map(|bytes| bytesrepr::deserialize(bytes.into_inner().into()).unwrap())
  }

node/src/components/binary_port.rs

@@ -394,7 +394,7 @@ where
  BinaryResponse::new_error(ErrorCode::FunctionDisabled, protocol_version)
  } else {
  let req = TrieRequest::new(trie_key, None);
- match effect_builder.get_trie(req).await.into_legacy() {
+ match effect_builder.get_trie(req).await.into_raw() {
  Ok(result) => BinaryResponse::from_value(
  GetTrieFullResult::new(result.map(TrieRaw::into_inner)),
  protocol_version,

node/src/components/contract_runtime.rs

@@ -767,7 +767,7 @@ impl ContractRuntime {
  let req = TrieRequest::new(trie_key, Some(chunk_index));
  let maybe_raw = data_access_layer
  .trie(req)
- .into_legacy()
+ .into_raw()
  .map_err(ContractRuntimeError::FailedToRetrieveTrieById)?;
  let ret = match maybe_raw {
  Some(raw) => Some(TrieOrChunk::new(raw.into(), chunk_index)?),

smart_contracts/contract/src/ext_ffi.rs

@@ -474,8 +474,8 @@ extern "C" {
  /// * `version_ptr` - output parameter where new version assigned by host is set
  /// * `entry_points_ptr` - pointer to serialized [`casper_types::EntryPoints`]
  /// * `entry_points_size` - size of serialized [`casper_types::EntryPoints`]
- /// * `named_keys_ptr` - pointer to serialized [`casper_types::contracts::NamedKeys`]
- /// * `named_keys_size` - size of serialized [`casper_types::contracts::NamedKeys`]
+ /// * `named_keys_ptr` - pointer to serialized [`casper_types::addressable_entity::NamedKeys`]
+ /// * `named_keys_size` - size of serialized [`casper_types::addressable_entity::NamedKeys`]
  /// * `output_ptr` - pointer to a memory where host assigned contract hash is set to
  /// * `output_size` - size of memory area that host can write to
  /// * `bytes_written_ptr` - pointer to a value where host will set a number of bytes written to

storage/src/block_store/block_provider.rs

@@ -2,17 +2,22 @@ use super::error::BlockStoreError;
 
 /// A block store that supports read/write operations consistently.
 pub trait BlockStoreProvider {
+ /// Reader alias.
  type Reader<'a>: BlockStoreTransaction
  where
  Self: 'a;
+ /// ReaderWriter alias.
  type ReaderWriter<'a>: BlockStoreTransaction
  where
  Self: 'a;
 
+ /// Check out read only handle.
  fn checkout_ro(&self) -> Result<Self::Reader<'_>, BlockStoreError>;
+ /// Check out read write handle.
  fn checkout_rw(&mut self) -> Result<Self::ReaderWriter<'_>, BlockStoreError>;
 }
 
+/// Block store transaction.
 pub trait BlockStoreTransaction {
  /// Commit changes to the block store.
  fn commit(self) -> Result<(), BlockStoreError>;
@@ -21,12 +26,18 @@ pub trait BlockStoreTransaction {
  fn rollback(self);
 }
 
+/// Data reader definition.
 pub trait DataReader<K, T> {
+ /// Read item at key.
  fn read(&self, key: K) -> Result<Option<T>, BlockStoreError>;
+ /// Returns true if item exists at key, else false.
  fn exists(&self, key: K) -> Result<bool, BlockStoreError>;
 }
 
+/// Data write definition.
 pub trait DataWriter<K, T> {
+ /// Write item to store and return key.
  fn write(&mut self, data: &T) -> Result<K, BlockStoreError>;
+ /// Delete item at key from store.
  fn delete(&mut self, key: K) -> Result<(), BlockStoreError>;
 }

storage/src/block_store/error.rs

@@ -2,6 +2,7 @@ use casper_types::{BlockHash, EraId, TransactionHash};
 use std::fmt::Debug;
 use thiserror::Error;
 
+/// Block store error.
 #[derive(Debug, Error)]
 pub enum BlockStoreError {
  /// Found a duplicate block entry of the specified height.

storage/src/block_store/lmdb/indexed_lmdb_block_store.rs

@@ -27,6 +27,7 @@ use casper_types::{
  BlockSignatures, Digest, EraId, ProtocolVersion, Transaction, TransactionHash, Transfer,
 };
 
+/// Indexed lmdb block store.
 #[derive(DataSize, Debug)]
 pub struct IndexedLmdbBlockStore {
  /// Block store
@@ -124,6 +125,7 @@ impl IndexedLmdbBlockStore {
  Ok(())
  }
 
+ /// Ctor.
  pub fn new(
  block_store: LmdbBlockStore,
  hard_reset_to_start_of_era: Option<EraId>,

storage/src/block_store/lmdb/lmdb_block_store.rs

@@ -51,6 +51,7 @@ const OS_FLAGS: EnvironmentFlags = EnvironmentFlags::WRITE_MAP;
 #[cfg(target_os = "macos")]
 const OS_FLAGS: EnvironmentFlags = EnvironmentFlags::empty();
 
+/// Lmdb block store.
 #[derive(DataSize, Debug)]
 pub struct LmdbBlockStore {
  /// Storage location.
@@ -82,6 +83,7 @@ pub struct LmdbBlockStore {
 }
 
 impl LmdbBlockStore {
+ /// Ctor.
  pub fn new(root_path: &Path, total_size: usize) -> Result<Self, BlockStoreError> {
  // Create the environment and databases.
  let env = new_environment(total_size, root_path)?;
@@ -127,6 +129,7 @@ impl LmdbBlockStore {
  })
  }
 
+ /// Write finality signatures.
  pub fn write_finality_signatures(
  &self,
  txn: &mut RwTransaction,

storage/src/block_store/mod.rs

@@ -1,6 +1,8 @@
 mod block_provider;
 mod error;
+/// Block store lmdb logic.
 pub mod lmdb;
+/// Block store types.
 pub mod types;
 
 pub use block_provider::{BlockStoreProvider, BlockStoreTransaction, DataReader, DataWriter};

storage/src/block_store/types/approvals_hashes.rs

@@ -39,6 +39,7 @@ pub struct ApprovalsHashes {
 }
 
 impl ApprovalsHashes {
+ /// Ctor.
  pub fn new(
  block_hash: BlockHash,
  approvals_hashes: Vec<ApprovalsHash>,
@@ -51,6 +52,7 @@ impl ApprovalsHashes {
  }
  }
 
+ /// Verify block.
  pub fn verify(&self, block: &Block) -> Result<(), ApprovalsHashesValidationError> {
  if *self.merkle_proof_approvals.key() != Key::ChecksumRegistry {
  return Err(ApprovalsHashesValidationError::InvalidKeyType);
@@ -92,6 +94,7 @@ impl ApprovalsHashes {
  Ok(())
  }
 
+ /// Deploy ids.
  pub(crate) fn deploy_ids(
  &self,
  v1_block: &BlockV1,
@@ -106,6 +109,7 @@ impl ApprovalsHashes {
  .collect())
  }
 
+ /// Transaction ids.
  pub fn transaction_ids(
  &self,
  v2_block: &BlockV2,
@@ -119,10 +123,12 @@ impl ApprovalsHashes {
  .collect()
  }
 
+ /// Block hash.
  pub fn block_hash(&self) -> &BlockHash {
  &self.block_hash
  }
 
+ /// Approvals hashes.
  pub fn approvals_hashes(&self) -> Vec<ApprovalsHash> {
  self.approvals_hashes.clone()
  }
@@ -197,7 +203,9 @@ pub enum ApprovalsHashesValidationError {
  /// The state root hash implied by the Merkle proof doesn't match that in the block.
  #[error("state root hash implied by the Merkle proof doesn't match that in the block")]
  StateRootHashMismatch {
+ /// Proof state root hash.
  proof_state_root_hash: Digest,
+ /// Block state root hash.
  block_state_root_hash: Digest,
  },
 
@@ -212,10 +220,13 @@ pub enum ApprovalsHashesValidationError {
  /// The approvals checksum provided doesn't match one calculated from the approvals.
  #[error("provided approvals checksum doesn't match one calculated from the approvals")]
  ApprovalsChecksumMismatch {
+ /// Computed approvals checksum.
  computed_approvals_checksum: Digest,
+ /// Value in proof.
  value_in_proof: Digest,
  },
 
+ /// Variant mismatch.
  #[error("mismatch in variants: {0:?}")]
  #[data_size(skip)]
  VariantMismatch(Box<dyn Debug + Send + Sync>),

storage/src/block_store/types/block_hash_height_and_era.rs

@@ -6,10 +6,14 @@ use rand::Rng;
 use casper_types::testing::TestRng;
 use casper_types::{BlockHash, BlockHashAndHeight, EraId};
 
+/// Aggregates block identifying information.
 #[derive(Clone, Copy, Debug, DataSize)]
 pub struct BlockHashHeightAndEra {
+ /// Block hash.
  pub block_hash: BlockHash,
+ /// Block height.
  pub block_height: u64,
+ /// EraId
  pub era_id: EraId,
 }
 

storage/src/block_store/types/mod.rs

@@ -18,39 +18,62 @@ pub(crate) use approvals_hashes::LegacyApprovalsHashes;
 pub(crate) use deploy_metadata_v1::DeployMetadataV1;
 pub(in crate::block_store) use transfers::Transfers;
 
+/// Exeuction results.
 pub type ExecutionResults = HashMap<TransactionHash, ExecutionResult>;
 
+/// Transaction finalized approvals.
 pub struct TransactionFinalizedApprovals {
+ /// Transaction hash.
  pub transaction_hash: TransactionHash,
+ /// Finalized approvals.
  pub finalized_approvals: BTreeSet<Approval>,
 }
 
+/// Block execution results.
 pub struct BlockExecutionResults {
+ /// Block info.
  pub block_info: BlockHashHeightAndEra,
+ /// Execution results.
  pub exec_results: ExecutionResults,
 }
 
+/// Block transfers.
 pub struct BlockTransfers {
+ /// Block hash.
  pub block_hash: BlockHash,
+ /// Transfers.
  pub transfers: Vec<Transfer>,
 }
 
+/// State store.
 pub struct StateStore {
+ /// Key.
  pub key: Cow<'static, [u8]>,
+ /// Value.
  pub value: Vec<u8>,
 }
 
+/// State store key.
 pub struct StateStoreKey(pub(super) Cow<'static, [u8]>);
 
 impl StateStoreKey {
+ /// Ctor.
  pub fn new(key: Cow<'static, [u8]>) -> Self {
  StateStoreKey(key)
  }
 }
 
+/// Block tip anchor.
 pub struct Tip;
+
+/// Latest switch block anchor.
 pub struct LatestSwitchBlock;
 
+/// Block height.
 pub type BlockHeight = u64;
+
+/// Switch block header alias.
 pub type SwitchBlockHeader = BlockHeader;
+
+/// Switch block alias.
 pub type SwitchBlock = Block;