Add subxt documentation (#546)

* Documentation for cli crate

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify calls generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify events generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify constants generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify storage generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add lib documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* macro: Remove `-f bytes` as this is the default

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt/client: Add examples

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* lib_doc: Add documentation to dedicated file

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Link documentation from file

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add more documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add Storage example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add rpc documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* metadata: Add documentation for errors

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add documentation for the `extrinsic` module

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add documentation for `events` module

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add `Static Metadata Validation` section

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add `Runtime Updates` section

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Fix link to documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* readme: Remove hardcoded versions

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Move documentation to dedicated folder

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Spaces between examples

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* More details for `types_mod_ident`

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add note for RuntimeGenerator

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Address feedback

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update codegen/src/api/constants.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/lib.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/metadata/metadata_type.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/storage.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Address feedback

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Fix cargo clippy

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update call example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add example for fetching constants

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Link to examples in subxt.md

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/constants.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/constants.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update subxt/src/extrinsic/mod.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update subxt/src/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update examples/examples/balance_transfer.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/extrinsic/mod.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/rpc.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/updates.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update docs example with `PolkadotExtrinsicParams`

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Remove extrinsic extra documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* examples: Remove similar transfer example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Apply cargo fmt

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

Co-authored-by: James Wilson <james@jsdw.me>
Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

subxt/src/lib.rs

@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with subxt.  If not, see <http://www.gnu.org/licenses/>.
 
-//! A library to **sub**mit e**xt**rinsics to a
-//! [substrate](https://github.com/paritytech/substrate) node via RPC.
-
+#![doc = include_str!("../../docs/subxt.md")]
 #![deny(
     bad_style,
     const_err,
@@ -126,7 +124,13 @@ pub use crate::{
     },
 };
 
-/// Call trait.
+/// Trait to uniquely identify the call (extrinsic)'s identity from the runtime metadata.
+///
+/// Generated API structures that represent each of the different possible
+/// calls to a node each implement this trait.
+///
+/// When encoding an extrinsic, we use this information to know how to map
+/// the call to the specific pallet and call index needed by a particular node.
 pub trait Call: Encode {
     /// Pallet name.
     const PALLET: &'static str;
@@ -139,7 +143,12 @@ pub trait Call: Encode {
     }
 }
 
-/// Event trait.
+/// Trait to uniquely identify the events's identity from the runtime metadata.
+///
+/// Generated API structures that represent an event implement this trait.
+///
+/// The trait is utilized to decode emitted events from a block, via obtaining the
+/// form of the `Event` from the metadata.
 pub trait Event: Decode {
     /// Pallet name.
     const PALLET: &'static str;