Add subxt documentation

README.md

@@ -22,81 +22,19 @@ subxt metadata -f bytes > metadata.scale
 This defaults to querying the metadata of a locally running node on the default `http://localhost:9933/`. If querying
 a different node then the `metadata` command accepts a `--url` argument.
 
-### Generating the runtime API from the downloaded metadata
+## Subxt Documentation
 
-Declare a module and decorate it with the `subxt` attribute which points at the downloaded metadata for the
-target runtime:
-
-```rust
-#[subxt::subxt(runtime_metadata_path = "metadata.scale")]
-pub mod node_runtime { }
-```
-
-**Important:** `runtime_metadata_path` resolves to a path relative to the directory where your crate's `Cargo.toml`
-resides ([`CARGO_MANIFEST_DIR`](https://doc.rust-lang.org/cargo/reference/environment-variables.html)), *not* relative to the source file.
-
-### Initializing the API client
-
-```rust
-use subxt::{ClientBuilder, DefaultConfig, SubstrateExtrinsicParams};
-
-let api = ClientBuilder::new()
-    .set_url("wss://rpc.polkadot.io:443")
-    .build()
-    .await?
-    .to_runtime_api::<node_runtime::RuntimeApi<DefaultConfig, SubstrateExtrinsicParams<DefaultConfig>>>();
-```
-
-The `RuntimeApi` type is generated by the `subxt` macro from the supplied metadata. This can be parameterized with user
-supplied implementations for the `Config` and `Extra` types, if the default implementations differ from the target
-chain.
-
-### Querying Storage
-
-Call the generated `RuntimeApi::storage()` method, followed by the `pallet_name()` and then the `storage_item_name()`.
-
-So in order to query `Balances::TotalIssuance`:
-
-```rust
-let total_issuance = api
-    .storage()
-    .balances()
-    .total_issuance(None)
-    .await
-    .unwrap()
-```
-
-### Submitting Extrinsics
-
-Submit an extrinsic, returning success once the transaction is validated and accepted into the pool:
-
-```rust
-use sp_keyring::AccountKeyring;
-use subxt::PairSigner;
-
-let signer = PairSigner::new(AccountKeyring::Alice.pair());
-let dest = AccountKeyring::Bob.to_account_id().into();
-
-let tx_hash = api
-    .tx()
-    .balances()
-    .transfer(dest, 10_000)
-    .sign_and_submit(&signer)
-    .await?;
-```
-
-For more advanced usage, which can wait for block inclusion and return any events triggered by the extrinsic, see the
-[balance transfer example](./examples/examples/balance_transfer.rs).
+For more details regarding utilizing subxt, please visit the [documentation](docs/subxt.md).
 
 ## Integration Testing
 
 Most tests require a running substrate node to communicate with. This is done by spawning an instance of the
-substrate node per test. It requires an executable binary `substrate` at [`polkadot-v0.9.10`](https://github.com/paritytech/substrate/releases/tag/polkadot-v0.9.10) on your path.
+substrate node per test. It requires an up-to-date `substrate` executable on your path.
 
 This can be installed from source via cargo:
 
 ```bash
-cargo install --git https://github.com/paritytech/substrate node-cli --tag=polkadot-v0.9.10 --force
+cargo install --git https://github.com/paritytech/substrate node-cli --force
 ```
 
 ## Real world usage

cli/src/main.rs

@@ -63,15 +63,15 @@ enum Command {
     /// Download metadata from a substrate node, for use with `subxt` codegen.
     #[structopt(name = "metadata")]
     Metadata {
-        /// the url of the substrate node to query for metadata
+        /// The url of the substrate node to query for metadata.
         #[structopt(
             name = "url",
             long,
             parse(try_from_str),
             default_value = "http://localhost:9933"
         )]
         url: url::Url,
-        /// the format of the metadata to display: `json`, `hex` or `bytes`
+        /// The format of the metadata to display: `json`, `hex` or `bytes`.
         #[structopt(long, short, default_value = "bytes")]
         format: String,
     },
@@ -81,10 +81,10 @@ enum Command {
     ///
     /// `subxt codegen | rustfmt --edition=2018 --emit=stdout`
     Codegen {
-        /// the url of the substrate node to query for metadata for codegen.
+        /// The url of the substrate node to query for metadata for codegen.
         #[structopt(name = "url", long, parse(try_from_str))]
         url: Option<url::Url>,
-        /// the path to the encoded metadata file.
+        /// The path to the encoded metadata file.
         #[structopt(short, long, parse(from_os_str))]
         file: Option<PathBuf>,
         /// Additional derives

codegen/src/api/calls.rs

@@ -20,7 +20,6 @@ use crate::types::{
 };
 use frame_metadata::{
     v14::RuntimeMetadataV14,
-    PalletCallMetadata,
     PalletMetadata,
 };
 use heck::{
@@ -35,13 +34,51 @@ use quote::{
 };
 use scale_info::form::PortableForm;
 
+/// Generate calls from the provided pallet's metadata.
+///
+/// The function creates a new module named `calls` under the pallet's module.
+/// ```ignore
+/// pub mod PalletName {
+///     pub mod calls {
+///     ...
+///     }
+/// }
+/// ```
+///
+/// The function generates the calls as rust structs that implement the `subxt::Call` trait
+/// to uniquely identify the call's identity when creating the extrinsic.
+///
+/// ```ignore
+/// pub struct CallName {
+///      pub call_param: type,
+/// }
+/// impl ::subxt::Call for CallName {
+/// ...
+/// }
+/// ```
+///
+/// Calls are extracted from the API and wrapped into the generated `TransactionApi` of
+/// each module.
+///
+/// # Arguments
+///
+/// - `metadata` - Runtime metadata from which the calls are generated.
+/// - `type_gen` - The type generator containing all types defined by metadata.
+/// - `pallet` - Pallet metadata from which the calls are generated.
+/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
 pub fn generate_calls(
     metadata: &RuntimeMetadataV14,
     type_gen: &TypeGenerator,
     pallet: &PalletMetadata<PortableForm>,
-    call: &PalletCallMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
 ) -> TokenStream2 {
+    // Early return if the pallet has no calls.
+    let call = if let Some(ref calls) = pallet.calls {
+        calls
+    } else {
+        return quote!()
+    };
+
     let mut struct_defs = super::generate_structs_from_variants(
         type_gen,
         call.ty.id(),

codegen/src/api/constants.rs

@@ -17,7 +17,6 @@
 use crate::types::TypeGenerator;
 use frame_metadata::{
     v14::RuntimeMetadataV14,
-    PalletConstantMetadata,
     PalletMetadata,
 };
 use heck::ToSnakeCase as _;
@@ -29,13 +28,41 @@ use quote::{
 };
 use scale_info::form::PortableForm;
 
+/// Generate constants from the provided pallet's metadata.
+///
+/// The function creates a new module named `constants` under the pallet's module.
+/// ```ignore
+/// pub mod PalletName {
+///     pub mod constants {
+///     ...
+///     }
+/// }
+/// ```
+///
+/// The constants are exposed via the `ConstantsApi` wrapper.
+///
+/// Although the constants are defined in the provided static metadata, the API
+/// ensures that the constants are returned from the runtime metadata of the node.
+/// This ensures that if the node's constants change value, we'll always see the latest values.
+///
+/// # Arguments
+///
+/// - `metadata` - Runtime metadata from which the calls are generated.
+/// - `type_gen` - The type generator containing all types defined by metadata
+/// - `pallet` - Pallet metadata from which the calls are generated.
+/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
 pub fn generate_constants(
     metadata: &RuntimeMetadataV14,
     type_gen: &TypeGenerator,
     pallet: &PalletMetadata<PortableForm>,
-    constants: &[PalletConstantMetadata<PortableForm>],
     types_mod_ident: &syn::Ident,
 ) -> TokenStream2 {
+    // Early return if the pallet has no constants.
+    if pallet.constants.is_empty() {
+        return quote!()
+    }
+    let constants = &pallet.constants;
+
     let constant_fns = constants.iter().map(|constant| {
         let fn_name = format_ident!("{}", constant.name.to_snake_case());
         let pallet_name = &pallet.name;

codegen/src/api/events.rs

@@ -15,20 +15,51 @@
 // along with subxt.  If not, see <http://www.gnu.org/licenses/>.
 
 use crate::types::TypeGenerator;
-use frame_metadata::{
-    PalletEventMetadata,
-    PalletMetadata,
-};
+use frame_metadata::PalletMetadata;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
 use scale_info::form::PortableForm;
 
+/// Generate events from the provided pallet metadata.
+///
+/// The function creates a new module named `events` under the pallet's module.
+/// ```ignore
+/// pub mod PalletName {
+///     pub mod events {
+///     ...
+///     }
+/// }
+/// ```
+///
+/// The function generates the events as rust structs that implement the `subxt::Event` trait
+/// to uniquely identify the event's identity when creating the extrinsic.
+///
+/// ```ignore
+/// pub struct EventName {
+///      pub event_param: type,
+/// }
+/// impl ::subxt::Event for EventName {
+/// ...
+/// }
+/// ```
+///
+/// # Arguments
+///
+/// - `type_gen` - The type generator containing all types defined by metadata.
+/// - `pallet` - Pallet metadata from which the events are generated.
+/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
 pub fn generate_events(
     type_gen: &TypeGenerator,
     pallet: &PalletMetadata<PortableForm>,
-    event: &PalletEventMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
 ) -> TokenStream2 {
+    // Early return if the pallet has no events.
+    let event = if let Some(ref event) = pallet.event {
+        event
+    } else {
+        return quote!()
+    };
+
     let struct_defs = super::generate_structs_from_variants(
         type_gen,
         event.ty.id(),