Skip to content

Commit

Permalink
Expand solana-sdk API docs. (solana-labs#29063)
Browse files Browse the repository at this point in the history
* Expand solana-sdk API docs.

* Update sdk/src/genesis_config.rs

Co-authored-by: Tyera <[email protected]>

* Update sdk/src/hard_forks.rs

Co-authored-by: Tyera <[email protected]>

* Update sdk/src/builtins.rs

Co-authored-by: Tyera <[email protected]>

* Update sdk/src/builtins.rs

Co-authored-by: Tyera <[email protected]>

* Update sdk/src/rpc_port.rs

Co-authored-by: Tyera <[email protected]>

* Update sdk/src/lib.rs

Co-authored-by: Tyera <[email protected]>

* Clarify derivation_path docs

* 'entry point' -> 'entrypoint'

Co-authored-by: Tyera <[email protected]>
  • Loading branch information
brson and CriesofCarrots authored Dec 22, 2022
1 parent bf18613 commit edd5f6f
Show file tree
Hide file tree
Showing 37 changed files with 137 additions and 21 deletions.
6 changes: 3 additions & 3 deletions sdk/program/src/entrypoint.rs
Original file line number Diff line number Diff line change
@@ -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.
//!
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
///
Expand Down
6 changes: 3 additions & 3 deletions sdk/program/src/entrypoint_deprecated.rs
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion sdk/program/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::{
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/account.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! The Solana [`Account`] type.
use {
crate::{
clock::{Epoch, INITIAL_RENT_EPOCH},
Expand Down
3 changes: 2 additions & 1 deletion sdk/src/account_utils.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
//! useful extras for Account state
//! Useful extras for `Account` state.
use {
crate::{
account::{Account, AccountSharedData},
Expand Down
4 changes: 2 additions & 2 deletions sdk/src/builtins.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! Solana builtin helper macros
//! Solana helper macros for declaring built-in programs.
#[rustversion::since(1.46.0)]
#[macro_export]
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/commitment_config.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Definitions of commitment levels.
#![allow(deprecated)]
#![cfg(feature = "full")]

Expand Down
2 changes: 2 additions & 0 deletions sdk/src/compute_budget.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! The compute budget native program.
#![cfg(feature = "full")]

use {
Expand Down
11 changes: 11 additions & 0 deletions sdk/src/derivation_path.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/deserialize_utils.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Serde helpers.
use serde::{Deserialize, Deserializer};

/// This helper function enables successful deserialization of versioned structs; new structs may
Expand Down
4 changes: 4 additions & 0 deletions sdk/src/ed25519_instruction.rs
Original file line number Diff line number Diff line change
@@ -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 {
Expand Down
6 changes: 6 additions & 0 deletions sdk/src/entrypoint.rs
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
9 changes: 9 additions & 0 deletions sdk/src/entrypoint_deprecated.rs
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
6 changes: 6 additions & 0 deletions sdk/src/epoch_info.rs
Original file line number Diff line number Diff line change
@@ -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)]
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/exit.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Used by validators to run events on exit.
use std::fmt;

#[derive(Default)]
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/fee.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Fee structures.
use crate::native_token::sol_to_lamports;

/// A fee and its associated compute unit limit
Expand Down
2 changes: 1 addition & 1 deletion sdk/src/genesis_config.rs
Original file line number Diff line number Diff line change
@@ -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")]

Expand Down
4 changes: 2 additions & 2 deletions sdk/src/hard_forks.rs
Original file line number Diff line number Diff line change
@@ -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")]

Expand Down
7 changes: 6 additions & 1 deletion sdk/src/hash.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
38 changes: 35 additions & 3 deletions sdk/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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))]
Expand Down Expand Up @@ -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
///
Expand All @@ -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
///
Expand All @@ -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;
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/native_loader.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! The native loader native program.
use crate::{
account::{
Account, AccountSharedData, InheritableAccountFields, DUMMY_INHERITABLE_ACCOUNT_FIELDS,
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/nonce_account.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Functions related to nonce accounts.
use {
crate::{
account::{AccountSharedData, ReadableAccount},
Expand Down
2 changes: 1 addition & 1 deletion sdk/src/offchain_message.rs
Original file line number Diff line number Diff line change
@@ -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")]

Expand Down
2 changes: 2 additions & 0 deletions sdk/src/packet.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! The definition of a Solana network packet.
use {
bincode::{Options, Result},
bitflags::bitflags,
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/poh_config.rs
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
2 changes: 1 addition & 1 deletion sdk/src/precompiles.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! Solana precompiled programs
//! Solana precompiled programs.
#![cfg(feature = "full")]

Expand Down
4 changes: 4 additions & 0 deletions sdk/src/program_utils.rs
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/pubkey.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Solana account addresses.
pub use solana_program::pubkey::*;

/// New random Pubkey for tests and benchmarks.
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/quic.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/recent_blockhashes_account.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Helpers for the recent blockhashes sysvar.
#[allow(deprecated)]
use solana_program::sysvar::recent_blockhashes::{
IntoIterSorted, IterItem, RecentBlockhashes, MAX_ENTRIES,
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/reward_type.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Enumeration of reward types.
use std::fmt;

#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, AbiExample, AbiEnumVisitor, Clone, Copy)]
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/rpc_port.rs
Original file line number Diff line number Diff line change
@@ -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";
Expand Down
4 changes: 4 additions & 0 deletions sdk/src/shred_version.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
//! Calculation of [shred] versions.
//!
//! [shred]: https://docs.solana.com/terminology#shred
#![cfg(feature = "full")]

use solana_sdk::{
Expand Down
2 changes: 1 addition & 1 deletion sdk/src/signature.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/signer/mod.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Abstractions and implementations for transaction signers.
#![cfg(feature = "full")]

use {
Expand Down
2 changes: 1 addition & 1 deletion sdk/src/transaction_context.rs
Original file line number Diff line number Diff line change
@@ -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"))]
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/transport.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Defines the [`TransportError`] type.
#![cfg(feature = "full")]

use {crate::transaction::TransactionError, std::io, thiserror::Error};
Expand Down

0 comments on commit edd5f6f

Please sign in to comment.