Documentation for compiled classes the storage (#838)

crates/papyrus_storage/src/compiled_class.rs

@@ -1,3 +1,36 @@
+//! Interface for handling data related to Starknet [compiled classes (Cairo assembly, or CASM)](https://docs.rs/cairo-lang-starknet/latest/cairo_lang_starknet/casm_contract_class/struct.CasmContractClass.html).
+//!
+//! The compiled class is the result of compiling a Cairo program.
+//! Import [`CasmStorageReader`] and [`CasmStorageWriter`] to read and write data related to the
+//! compiled classes using a [`StorageTxn`].
+//! # Example
+//! ```
+//! use papyrus_storage::open_storage;
+//! # use papyrus_storage::db::DbConfig;
+//! # use starknet_api::core::ChainId;
+//! use cairo_lang_starknet::casm_contract_class::CasmContractClass;
+//! use papyrus_storage::compiled_class::{CasmStorageReader, CasmStorageWriter};
+//! use starknet_api::core::ClassHash;
+//!
+//! # let dir_handle = tempfile::tempdir().unwrap();
+//! # let dir = dir_handle.path().to_path_buf();
+//! # let db_config = DbConfig {
+//! #     path_prefix: dir,
+//! #     chain_id: ChainId("SN_MAIN".to_owned()),
+//! #     min_size: 1 << 20,    // 1MB
+//! #     max_size: 1 << 35,    // 32GB
+//! #     growth_step: 1 << 26, // 64MB
+//! # };
+//! let (reader, mut writer) = open_storage(db_config)?;
+//! writer
+//!     .begin_rw_txn()?                                                    // Start a RW transaction.
+//!     .append_casm(&ClassHash::default(), &CasmContractClass::default())? // Append a compiled class.
+//!     .commit()?;                                                         // Commit the transaction.
+//! let casm = reader.begin_ro_txn()?.get_casm(&ClassHash::default())?;
+//! assert_eq!(casm, Some(CasmContractClass::default()));
+//! # Ok::<(), papyrus_storage::StorageError>(())
+//! ```
+
 #[cfg(test)]
 #[path = "compiled_class_test.rs"]
 mod casm_test;
@@ -10,12 +43,18 @@ use starknet_api::state::ThinStateDiff;
 use crate::db::{DbError, DbTransaction, TableHandle, TransactionKind, RW};
 use crate::{MarkerKind, MarkersTable, StorageError, StorageResult, StorageTxn};
 
+/// Interface for reading data related to the compiled classes.
 pub trait CasmStorageReader {
     /// Returns the Cairo assembly of a class given its Sierra class hash.
     fn get_casm(&self, class_hash: &ClassHash) -> StorageResult<Option<CasmContractClass>>;
+    /// The block marker is the first block number that doesn't exist yet.
+    ///
+    /// Note: If the last blocks don't contain any declared classes, the marker will point at the
+    /// block after the last block that had declared classes.
     fn get_compiled_class_marker(&self) -> StorageResult<BlockNumber>;
 }
 
+/// Interface for writing data related to the compiled classes.
 pub trait CasmStorageWriter
 where
     Self: Sized,