diff --git a/sdk/program/src/entrypoint.rs b/sdk/program/src/entrypoint.rs index ed80b30c9f..5d28cc1dd2 100644 --- a/sdk/program/src/entrypoint.rs +++ b/sdk/program/src/entrypoint.rs @@ -1,4 +1,4 @@ -//! The Rust-based BPF program entry point supported by the latest BPF loader. +//! The Rust-based BPF program entrypoint supported by the latest BPF loader. //! //! For more information see the [`bpf_loader`] module. //! @@ -39,7 +39,7 @@ pub const HEAP_LENGTH: usize = 32 * 1024; /// Value used to indicate that a serialized account is not a duplicate pub const NON_DUP_MARKER: u8 = u8::MAX; -/// Declare the program entry point and set up global handlers. +/// Declare the program entrypoint and set up global handlers. /// /// This macro emits the common boilerplate necessary to begin program /// execution, calling a provided function to process the program instruction @@ -91,7 +91,7 @@ pub const NON_DUP_MARKER: u8 = u8::MAX; /// /// # Examples /// -/// Defining an entry point and making it conditional on the `no-entrypoint` +/// Defining an entrypoint and making it conditional on the `no-entrypoint` /// feature. Although the `entrypoint` module is written inline in this example, /// it is common to put it into its own file. /// diff --git a/sdk/program/src/entrypoint_deprecated.rs b/sdk/program/src/entrypoint_deprecated.rs index d455d6daff..05df3ccd78 100644 --- a/sdk/program/src/entrypoint_deprecated.rs +++ b/sdk/program/src/entrypoint_deprecated.rs @@ -1,4 +1,4 @@ -//! The Rust-based BPF program entry point supported by the original BPF loader. +//! The Rust-based BPF program entrypoint supported by the original BPF loader. //! //! The original BPF loader is deprecated and exists for backwards-compatibility //! reasons. This module should not be used by new programs. @@ -35,11 +35,11 @@ pub type ProcessInstruction = /// Programs indicate success with a return value of 0 pub const SUCCESS: u64 = 0; -/// Declare the program entry point. +/// Declare the program entrypoint. /// /// Deserialize the program input arguments and call /// the user defined `process_instruction` function. -/// Users must call this macro otherwise an entry point for +/// Users must call this macro otherwise an entrypoint for /// their program will not be created. #[macro_export] macro_rules! entrypoint_deprecated { diff --git a/sdk/program/src/lib.rs b/sdk/program/src/lib.rs index 29c7ccd03b..199b8f273f 100644 --- a/sdk/program/src/lib.rs +++ b/sdk/program/src/lib.rs @@ -546,7 +546,7 @@ pub mod config { } } -/// A vector of Solana SDK IDs +/// A vector of Solana SDK IDs. pub mod sdk_ids { use { crate::{ diff --git a/sdk/src/account.rs b/sdk/src/account.rs index 9e91867c9c..fca8f8b71f 100644 --- a/sdk/src/account.rs +++ b/sdk/src/account.rs @@ -1,3 +1,5 @@ +//! The Solana [`Account`] type. + use { crate::{ clock::{Epoch, INITIAL_RENT_EPOCH}, diff --git a/sdk/src/account_utils.rs b/sdk/src/account_utils.rs index 226fcb8323..e6e6a7bccd 100644 --- a/sdk/src/account_utils.rs +++ b/sdk/src/account_utils.rs @@ -1,4 +1,5 @@ -//! useful extras for Account state +//! Useful extras for `Account` state. + use { crate::{ account::{Account, AccountSharedData}, diff --git a/sdk/src/builtins.rs b/sdk/src/builtins.rs index 4c3b7c21f1..e837abcdb2 100644 --- a/sdk/src/builtins.rs +++ b/sdk/src/builtins.rs @@ -1,4 +1,4 @@ -//! Solana builtin helper macros +//! Solana helper macros for declaring built-in programs. #[rustversion::since(1.46.0)] #[macro_export] @@ -58,7 +58,7 @@ macro_rules! declare_builtin_name { }; } -/// Convenience macro to declare a builtin +/// Convenience macro to declare a built-in program. /// /// bs58_string: bs58 string representation the program's id /// name: Name of the program diff --git a/sdk/src/commitment_config.rs b/sdk/src/commitment_config.rs index 2626ce04f5..f0068659f4 100644 --- a/sdk/src/commitment_config.rs +++ b/sdk/src/commitment_config.rs @@ -1,3 +1,5 @@ +//! Definitions of commitment levels. + #![allow(deprecated)] #![cfg(feature = "full")] diff --git a/sdk/src/compute_budget.rs b/sdk/src/compute_budget.rs index 94a9f091e8..ec81b10f20 100644 --- a/sdk/src/compute_budget.rs +++ b/sdk/src/compute_budget.rs @@ -1,3 +1,5 @@ +//! The compute budget native program. + #![cfg(feature = "full")] use { diff --git a/sdk/src/derivation_path.rs b/sdk/src/derivation_path.rs index 0f14e39e17..83d8dd208e 100644 --- a/sdk/src/derivation_path.rs +++ b/sdk/src/derivation_path.rs @@ -1,3 +1,14 @@ +//! [BIP-44] derivation paths. +//! +//! [BIP-44]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki +//! +//! Includes definitions and helpers for Solana derivation paths. +//! The standard Solana BIP-44 derivation path prefix is +//! +//! > `m/44'/501'` +//! +//! with 501 being the Solana coin type. + use { core::{iter::IntoIterator, slice::Iter}, derivation_path::{ChildIndex, DerivationPath as DerivationPathInner}, diff --git a/sdk/src/deserialize_utils.rs b/sdk/src/deserialize_utils.rs index a5c098dc86..2d1464c17b 100644 --- a/sdk/src/deserialize_utils.rs +++ b/sdk/src/deserialize_utils.rs @@ -1,3 +1,5 @@ +//! Serde helpers. + use serde::{Deserialize, Deserializer}; /// This helper function enables successful deserialization of versioned structs; new structs may diff --git a/sdk/src/ed25519_instruction.rs b/sdk/src/ed25519_instruction.rs index a735611486..57f36e6529 100644 --- a/sdk/src/ed25519_instruction.rs +++ b/sdk/src/ed25519_instruction.rs @@ -1,3 +1,7 @@ +//! Instructions for the [ed25519 native program][np]. +//! +//! [np]: https://docs.solana.com/developing/runtime-facilities/programs#ed25519-program + #![cfg(feature = "full")] use { diff --git a/sdk/src/entrypoint.rs b/sdk/src/entrypoint.rs index 34053f73df..e83bdf0575 100644 --- a/sdk/src/entrypoint.rs +++ b/sdk/src/entrypoint.rs @@ -1,3 +1,9 @@ +//! The Rust-based BPF program entrypoint supported by the latest BPF loader. +//! +//! For more information see the [`bpf_loader`] module. +//! +//! [`bpf_loader`]: crate::bpf_loader + pub use solana_program::entrypoint::*; #[macro_export] diff --git a/sdk/src/entrypoint_deprecated.rs b/sdk/src/entrypoint_deprecated.rs index 419c0f66ce..c75b9c47a5 100644 --- a/sdk/src/entrypoint_deprecated.rs +++ b/sdk/src/entrypoint_deprecated.rs @@ -1,3 +1,12 @@ +//! The Rust-based BPF program entrypoint supported by the original BPF loader. +//! +//! The original BPF loader is deprecated and exists for backwards-compatibility +//! reasons. This module should not be used by new programs. +//! +//! For more information see the [`bpf_loader_deprecated`] module. +//! +//! [`bpf_loader_deprecated`]: crate::bpf_loader_deprecated + pub use solana_program::entrypoint_deprecated::*; #[macro_export] diff --git a/sdk/src/epoch_info.rs b/sdk/src/epoch_info.rs index 5b6bd7d34e..24106e2a67 100644 --- a/sdk/src/epoch_info.rs +++ b/sdk/src/epoch_info.rs @@ -1,3 +1,9 @@ +//! Information about the current epoch. +//! +//! As returned by the [`getEpochInfo`] RPC method. +//! +//! [`getEpochInfo`]: https://docs.solana.com/developing/clients/jsonrpc-api#getepochinfo + use crate::clock::{Epoch, Slot}; #[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq)] diff --git a/sdk/src/exit.rs b/sdk/src/exit.rs index ab6edf0779..674a71bba4 100644 --- a/sdk/src/exit.rs +++ b/sdk/src/exit.rs @@ -1,3 +1,5 @@ +//! Used by validators to run events on exit. + use std::fmt; #[derive(Default)] diff --git a/sdk/src/fee.rs b/sdk/src/fee.rs index a53db7336d..27556b63a3 100644 --- a/sdk/src/fee.rs +++ b/sdk/src/fee.rs @@ -1,3 +1,5 @@ +//! Fee structures. + use crate::native_token::sol_to_lamports; /// A fee and its associated compute unit limit diff --git a/sdk/src/genesis_config.rs b/sdk/src/genesis_config.rs index 7b3dde3ca2..ca75ebda44 100644 --- a/sdk/src/genesis_config.rs +++ b/sdk/src/genesis_config.rs @@ -1,4 +1,4 @@ -//! The `genesis_config` module is a library for generating the chain's genesis config. +//! The chain's genesis config. #![cfg(feature = "full")] diff --git a/sdk/src/hard_forks.rs b/sdk/src/hard_forks.rs index a83168ce37..878645d243 100644 --- a/sdk/src/hard_forks.rs +++ b/sdk/src/hard_forks.rs @@ -1,5 +1,5 @@ -//! The `hard_forks` module is used to maintain the list of slot boundaries for when a hard fork -//! should occur. +//! The list of slot boundaries at which a hard fork should +//! occur. #![cfg(feature = "full")] diff --git a/sdk/src/hash.rs b/sdk/src/hash.rs index c8326220bf..ddc1d5866f 100644 --- a/sdk/src/hash.rs +++ b/sdk/src/hash.rs @@ -1,6 +1,11 @@ +//! Hashing with the [SHA-256] hash function, and a general [`Hash`] type. +//! +//! [SHA-256]: https://en.wikipedia.org/wiki/SHA-2 +//! [`Hash`]: struct@Hash + pub use solana_program::hash::*; -/// random hash value for tests and benchmarks. +/// Random hash value for tests and benchmarks. #[cfg(feature = "full")] pub fn new_rand(rng: &mut R) -> Hash where diff --git a/sdk/src/lib.rs b/sdk/src/lib.rs index 81214d7e79..aa4ab7f8a7 100644 --- a/sdk/src/lib.rs +++ b/sdk/src/lib.rs @@ -1,3 +1,34 @@ +//! The Solana host and client SDK. +//! +//! This is the base library for all off-chain programs that interact with +//! Solana or otherwise operate on Solana data structures. On-chain programs +//! instead use the [`solana-program`] crate, the modules of which are +//! re-exported by this crate, like the relationship between the Rust +//! `core` and `std` crates. As much of the functionality of this crate is +//! provided by `solana-program`, see that crate's documentation for an +//! overview. +//! +//! [`solana-program`]: https://docs.rs/solana-program +//! +//! Many of the modules in this crate are primarily of use to the Solana runtime +//! itself. Additional crates provide capabilities built on `solana-sdk`, and +//! many programs will need to link to those crates as well, particularly for +//! clients communicating with Solana nodes over RPC. +//! +//! Such crates include: +//! +//! - [`solana-client`] - For interacting with a Solana node via the [JSON-RPC API][json]. +//! - [`solana-cli-config`] - Loading and saving the Solana CLI configuration file. +//! - [`solana-clap-utils`] - Routines for setting up the CLI using [`clap`], as +//! used by the Solana CLI. Includes functions for loading all types of +//! signers supported by the CLI. +//! +//! [`solana-client`]: https://docs.rs/solana-client +//! [`solana-cli-config`]: https://docs.rs/solana-cli-config +//! [`solana-clap-utils`]: https://docs.rs/solana-clap-utils +//! [json]: https://docs.solana.com/developing/clients/jsonrpc-api +//! [`clap`]: https://docs.rs/clap + #![allow(incomplete_features)] #![cfg_attr(RUSTC_WITH_SPECIALIZATION, feature(specialization))] #![cfg_attr(RUSTC_NEEDS_PROC_MACRO_HYGIENE, feature(proc_macro_hygiene))] @@ -68,9 +99,9 @@ pub mod transaction_context; pub mod transport; pub mod wasm; -/// Same as `declare_id` except report that this id has been deprecated +/// Same as `declare_id` except report that this id has been deprecated. pub use solana_sdk_macro::declare_deprecated_id; -/// Convenience macro to declare a static public key and functions to interact with it +/// Convenience macro to declare a static public key and functions to interact with it. /// /// Input: a single literal base58 string representation of a program's id /// @@ -92,7 +123,7 @@ pub use solana_sdk_macro::declare_deprecated_id; /// assert_eq!(id(), my_id); /// ``` pub use solana_sdk_macro::declare_id; -/// Convenience macro to define a static public key +/// Convenience macro to define a static public key. /// /// Input: a single literal base58 string representation of a Pubkey /// @@ -108,6 +139,7 @@ pub use solana_sdk_macro::declare_id; /// assert_eq!(ID, my_id); /// ``` pub use solana_sdk_macro::pubkey; +/// Convenience macro to define multiple static public keys. pub use solana_sdk_macro::pubkeys; #[rustversion::since(1.46.0)] pub use solana_sdk_macro::respan; diff --git a/sdk/src/native_loader.rs b/sdk/src/native_loader.rs index 68b835e1bb..3f10fc527a 100644 --- a/sdk/src/native_loader.rs +++ b/sdk/src/native_loader.rs @@ -1,3 +1,5 @@ +//! The native loader native program. + use crate::{ account::{ Account, AccountSharedData, InheritableAccountFields, DUMMY_INHERITABLE_ACCOUNT_FIELDS, diff --git a/sdk/src/nonce_account.rs b/sdk/src/nonce_account.rs index 19cbca73b5..255011a7bb 100644 --- a/sdk/src/nonce_account.rs +++ b/sdk/src/nonce_account.rs @@ -1,3 +1,5 @@ +//! Functions related to nonce accounts. + use { crate::{ account::{AccountSharedData, ReadableAccount}, diff --git a/sdk/src/offchain_message.rs b/sdk/src/offchain_message.rs index 344367edcf..d6888ca198 100644 --- a/sdk/src/offchain_message.rs +++ b/sdk/src/offchain_message.rs @@ -1,4 +1,4 @@ -//! Off-Chain Message container for storing non-transaction messages. +//! Off-chain message container for storing non-transaction messages. #![cfg(feature = "full")] diff --git a/sdk/src/packet.rs b/sdk/src/packet.rs index 7fa9d1b3a1..3301b7d42e 100644 --- a/sdk/src/packet.rs +++ b/sdk/src/packet.rs @@ -1,3 +1,5 @@ +//! The definition of a Solana network packet. + use { bincode::{Options, Result}, bitflags::bitflags, diff --git a/sdk/src/poh_config.rs b/sdk/src/poh_config.rs index 471c1e6d13..864004f11b 100644 --- a/sdk/src/poh_config.rs +++ b/sdk/src/poh_config.rs @@ -1,3 +1,5 @@ +//! Definitions of Solana's proof of history. + use { crate::{clock::DEFAULT_TICKS_PER_SECOND, unchecked_div_by_const}, std::time::Duration, diff --git a/sdk/src/precompiles.rs b/sdk/src/precompiles.rs index 90691dba33..6270c82f4e 100644 --- a/sdk/src/precompiles.rs +++ b/sdk/src/precompiles.rs @@ -1,4 +1,4 @@ -//! Solana precompiled programs +//! Solana precompiled programs. #![cfg(feature = "full")] diff --git a/sdk/src/program_utils.rs b/sdk/src/program_utils.rs index e0ca9975da..57ae1017f9 100644 --- a/sdk/src/program_utils.rs +++ b/sdk/src/program_utils.rs @@ -1,3 +1,7 @@ +//! Contains a single utility function for deserializing from [bincode]. +//! +//! [bincode]: https://docs.rs/bincode + use crate::instruction::InstructionError; /// Deserialize with a limit based the maximum amount of data a program can expect to get. diff --git a/sdk/src/pubkey.rs b/sdk/src/pubkey.rs index 4032c19eca..874710ba41 100644 --- a/sdk/src/pubkey.rs +++ b/sdk/src/pubkey.rs @@ -1,3 +1,5 @@ +//! Solana account addresses. + pub use solana_program::pubkey::*; /// New random Pubkey for tests and benchmarks. diff --git a/sdk/src/quic.rs b/sdk/src/quic.rs index 5038ab0ee4..b39b7e7001 100644 --- a/sdk/src/quic.rs +++ b/sdk/src/quic.rs @@ -1,3 +1,5 @@ +//! Definitions related to Solana over QUIC. + pub const QUIC_PORT_OFFSET: u16 = 6; // Empirically found max number of concurrent streams // that seems to maximize TPS on GCE (higher values don't seem to diff --git a/sdk/src/recent_blockhashes_account.rs b/sdk/src/recent_blockhashes_account.rs index 73cb1ecf72..a57b500c2b 100644 --- a/sdk/src/recent_blockhashes_account.rs +++ b/sdk/src/recent_blockhashes_account.rs @@ -1,3 +1,5 @@ +//! Helpers for the recent blockhashes sysvar. + #[allow(deprecated)] use solana_program::sysvar::recent_blockhashes::{ IntoIterSorted, IterItem, RecentBlockhashes, MAX_ENTRIES, diff --git a/sdk/src/reward_type.rs b/sdk/src/reward_type.rs index feba745993..84bddfcfb9 100644 --- a/sdk/src/reward_type.rs +++ b/sdk/src/reward_type.rs @@ -1,3 +1,5 @@ +//! Enumeration of reward types. + use std::fmt; #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, AbiExample, AbiEnumVisitor, Clone, Copy)] diff --git a/sdk/src/rpc_port.rs b/sdk/src/rpc_port.rs index 3a38cef458..0bbaa1d7fe 100644 --- a/sdk/src/rpc_port.rs +++ b/sdk/src/rpc_port.rs @@ -1,3 +1,5 @@ +//! RPC default port numbers. + /// Default port number for JSON RPC API pub const DEFAULT_RPC_PORT: u16 = 8899; pub const DEFAULT_RPC_PORT_STR: &str = "8899"; diff --git a/sdk/src/shred_version.rs b/sdk/src/shred_version.rs index d253f30a33..6017202c9d 100644 --- a/sdk/src/shred_version.rs +++ b/sdk/src/shred_version.rs @@ -1,3 +1,7 @@ +//! Calculation of [shred] versions. +//! +//! [shred]: https://docs.solana.com/terminology#shred + #![cfg(feature = "full")] use solana_sdk::{ diff --git a/sdk/src/signature.rs b/sdk/src/signature.rs index ace0bf0981..02bd3667ab 100644 --- a/sdk/src/signature.rs +++ b/sdk/src/signature.rs @@ -1,4 +1,4 @@ -//! The `signature` module provides functionality for public, and private keys. +//! Functionality for public and private keys. #![cfg(feature = "full")] // legacy module paths diff --git a/sdk/src/signer/mod.rs b/sdk/src/signer/mod.rs index 84407ffc5e..f47b2840dc 100644 --- a/sdk/src/signer/mod.rs +++ b/sdk/src/signer/mod.rs @@ -1,3 +1,5 @@ +//! Abstractions and implementations for transaction signers. + #![cfg(feature = "full")] use { diff --git a/sdk/src/transaction_context.rs b/sdk/src/transaction_context.rs index eaff7c86a6..6f63812290 100644 --- a/sdk/src/transaction_context.rs +++ b/sdk/src/transaction_context.rs @@ -1,4 +1,4 @@ -//! Data shared between program runtime and built-in programs as well as SBF programs +//! Data shared between program runtime and built-in programs as well as SBF programs. #![deny(clippy::indexing_slicing)] #[cfg(not(target_os = "solana"))] diff --git a/sdk/src/transport.rs b/sdk/src/transport.rs index fe8b178faf..a9ec06c3fe 100644 --- a/sdk/src/transport.rs +++ b/sdk/src/transport.rs @@ -1,3 +1,5 @@ +//! Defines the [`TransportError`] type. + #![cfg(feature = "full")] use {crate::transaction::TransactionError, std::io, thiserror::Error};