client: Add crate level examples and features docs (#2779)

client/Cargo.toml

@@ -5,7 +5,7 @@ authors = ["Anchor Maintainers <accounts@200ms.io>"]
 rust-version = "1.60"
 edition = "2021"
 license = "Apache-2.0"
-description = "Rust client for Anchor programs"
+description = "An RPC client to interact with Anchor programs"
 
 [package.metadata.docs.rs]
 all-features = true

client/src/lib.rs

@@ -1,7 +1,64 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
-//! `anchor_client` provides an RPC client to send transactions and fetch
-//! deserialized accounts from Solana programs written in `anchor_lang`.
+//! An RPC client to interact with Solana programs written in [`anchor_lang`].
+//!
+//! # Examples
+//!
+//! A simple example that creates a client, sends a transaction and fetches an account:
+//!
+//! ```ignore
+//! use std::rc::Rc;
+//!
+//! use anchor_client::{
+//!     solana_sdk::{
+//!         signature::{read_keypair_file, Keypair},
+//!         signer::Signer,
+//!         system_program,
+//!     },
+//!     Client, Cluster,
+//! };
+//! use my_program::{accounts, instruction, MyAccount};
+//!
+//! fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     // Create client
+//!     let payer = read_keypair_file("keypair.json")?;
+//!     let client = Client::new(Cluster::Localnet, Rc::new(payer));
+//!
+//!     // Create program
+//!     let program = client.program(my_program::ID)?;
+//!
+//!     // Send a transaction
+//!     let my_account_kp = Keypair::new();
+//!     program
+//!         .request()
+//!         .accounts(accounts::Initialize {
+//!             my_account: my_account_kp.pubkey(),
+//!             payer: program.payer(),
+//!             system_program: system_program::ID,
+//!         })
+//!         .args(instruction::Initialize { field: 42 })
+//!         .signer(&my_account_kp)
+//!         .send()?;
+//!
+//!     // Fetch an account
+//!     let my_account: MyAccount = program.account(my_account_kp.pubkey())?;
+//!     assert_eq!(my_account.field, 42);
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! More examples can be found in [here].
+//!
+//! [here]: https://github.com/coral-xyz/anchor/tree/v0.29.0/client/example/src
+//!
+//! # Features
+//!
+//! The client is blocking by default. To enable asynchronous client, add `async` feature:
+//!
+//! ```toml
+//! anchor-client = { version = "0.29.0 ", features = ["async"] }
+//! ````
 
 use anchor_lang::solana_program::hash::Hash;
 use anchor_lang::solana_program::instruction::{AccountMeta, Instruction};