Expand solana-sdk API docs. (#29063)

* Expand solana-sdk API docs.

* Update sdk/src/genesis_config.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Update sdk/src/hard_forks.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Update sdk/src/builtins.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Update sdk/src/builtins.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Update sdk/src/rpc_port.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Update sdk/src/lib.rs

Co-authored-by: Tyera <teulberg@gmail.com>

* Clarify derivation_path docs

* 'entry point' -> 'entrypoint'

Co-authored-by: Tyera <teulberg@gmail.com>

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.
 ///

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 {

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::{

sdk/src/account.rs

@@ -1,3 +1,5 @@
+//! The Solana [`Account`] type.
+
 use {
     crate::{
         clock::{Epoch, INITIAL_RENT_EPOCH},

sdk/src/account_utils.rs

@@ -1,4 +1,5 @@
-//! useful extras for Account state
+//! Useful extras for `Account` state.
+
 use {
     crate::{
         account::{Account, AccountSharedData},

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

sdk/src/commitment_config.rs

@@ -1,3 +1,5 @@
+//! Definitions of commitment levels.
+
 #![allow(deprecated)]
 #![cfg(feature = "full")]
 

sdk/src/compute_budget.rs

@@ -1,3 +1,5 @@
+//! The compute budget native program.
+
 #![cfg(feature = "full")]
 
 use {

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},

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

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 {

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]

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]

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)]

sdk/src/exit.rs

@@ -1,3 +1,5 @@
+//! Used by validators to run events on exit.
+
 use std::fmt;
 
 #[derive(Default)]

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

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")]
 

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")]
 

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<R: ?Sized>(rng: &mut R) -> Hash
 where

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;

sdk/src/native_loader.rs

@@ -1,3 +1,5 @@
+//! The native loader native program.
+
 use crate::{
     account::{
         Account, AccountSharedData, InheritableAccountFields, DUMMY_INHERITABLE_ACCOUNT_FIELDS,

sdk/src/nonce_account.rs

@@ -1,3 +1,5 @@
+//! Functions related to nonce accounts.
+
 use {
     crate::{
         account::{AccountSharedData, ReadableAccount},

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")]
 

sdk/src/packet.rs

@@ -1,3 +1,5 @@
+//! The definition of a Solana network packet.
+
 use {
     bincode::{Options, Result},
     bitflags::bitflags,

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,

sdk/src/precompiles.rs

@@ -1,4 +1,4 @@
-//! Solana precompiled programs
+//! Solana precompiled programs.
 
 #![cfg(feature = "full")]
 

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.

sdk/src/pubkey.rs

@@ -1,3 +1,5 @@
+//! Solana account addresses.
+
 pub use solana_program::pubkey::*;
 
 /// New random Pubkey for tests and benchmarks.

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

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,

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)]

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";

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::{

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

sdk/src/signer/mod.rs

@@ -1,3 +1,5 @@
+//! Abstractions and implementations for transaction signers.
+
 #![cfg(feature = "full")]
 
 use {

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"))]

sdk/src/transport.rs

@@ -1,3 +1,5 @@
+//! Defines the [`TransportError`] type.
+
 #![cfg(feature = "full")]
 
 use {crate::transaction::TransactionError, std::io, thiserror::Error};