docs: add missing documentation comments for pop_contracts and `pop…

…_parachain` crates (#181)

* docs: comments in pop parachain crate

* docs: pop contracts documentation

* docs: fix feedback

* docs: apply feedback

* docs: apply feedback

crates/pop-contracts/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pop-contracts"
-description = "Library for generating, building, deploying and calling ink! smart contracts."
+description = "Library for generating, building, deploying, and calling ink! smart contracts."
 version = "0.1.0"
 license = "Apache-2.0"
 edition.workspace = true

crates/pop-contracts/README.md

@@ -1,8 +1,6 @@
 # pop-contracts
 
-A crate for generating, building, deploying and calling [`ink!`](https://github.com/paritytech/ink) Smart Contracts. 
-
-> :information_source: A [crates.io](https://crates.io/crates/pop-contracts) version will be available soon!
+A crate for generating, building, deploying, and calling [`ink!`](https://github.com/paritytech/ink) Smart Contracts. Used by [`pop-cli`](https://github.com/r0gue-io/pop-cli).
 
 ## Usage
 

crates/pop-contracts/src/build.rs

@@ -4,6 +4,7 @@ use std::path::PathBuf;
 
 use crate::utils::helpers::get_manifest_path;
 
+/// Build the smart contract located in the specified `path`.
 pub fn build_smart_contract(path: &Option<PathBuf>) -> anyhow::Result<String> {
 	let manifest_path = get_manifest_path(path)?;
 	// Default values

crates/pop-contracts/src/call.rs

@@ -16,6 +16,8 @@ use crate::utils::{
 	helpers::{get_manifest_path, parse_account, parse_balance},
 	signer::create_signer,
 };
+
+/// Attributes for the `call` command.
 pub struct CallOpts {
 	/// Path to the contract build folder.
 	pub path: Option<PathBuf>,
@@ -39,6 +41,12 @@ pub struct CallOpts {
 	pub execute: bool,
 }
 
+/// Prepare the preprocessed data for a contract `call`.
+///
+/// # Arguments
+///
+/// * `call_opts` - attributes for the `call` command.
+///
 pub async fn set_up_call(
 	call_opts: CallOpts,
 ) -> anyhow::Result<CallExec<DefaultConfig, DefaultEnvironment, Keypair>> {
@@ -67,6 +75,12 @@ pub async fn set_up_call(
 	return Ok(call_exec);
 }
 
+/// Simulate a smart contract call without modifying the state of the blockchain.
+///
+/// # Arguments
+///
+/// * `call_exec` - struct with the call to be executed.
+///
 pub async fn dry_run_call(
 	call_exec: &CallExec<DefaultConfig, DefaultEnvironment, Keypair>,
 ) -> anyhow::Result<String> {
@@ -93,6 +107,12 @@ pub async fn dry_run_call(
     }
 }
 
+/// Estimate the gas required for a contract call without modifying the state of the blockchain.
+///
+/// # Arguments
+///
+/// * `call_exec` - the preprocessed data to call a contract.
+///
 pub async fn dry_run_gas_estimate_call(
 	call_exec: &CallExec<DefaultConfig, DefaultEnvironment, Keypair>,
 ) -> anyhow::Result<Weight> {
@@ -116,6 +136,14 @@ pub async fn dry_run_gas_estimate_call(
     }
 }
 
+/// Call a smart contract on the blockchain.
+///
+/// # Arguments
+///
+/// * `call_exec` - struct with the call to be executed.
+/// * `gas_limit` - maximum amount of gas to be used for this call.
+/// * `url` - endpoint of the node which to send the call to.
+///
 pub async fn call_smart_contract(
 	call_exec: CallExec<DefaultConfig, DefaultEnvironment, Keypair>,
 	gas_limit: Weight,

crates/pop-contracts/src/lib.rs

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: GPL-3.0
+#![doc = include_str!("../README.md")]
 mod build;
 mod call;
 mod errors;
 mod new;
 mod test;
 mod up;
-pub mod utils;
+mod utils;
 
 pub use build::build_smart_contract;
 pub use call::{

crates/pop-contracts/src/new.rs

@@ -3,6 +3,12 @@ use crate::errors::Error;
 use contract_build::new_contract_project;
 use std::path::Path;
 
+/// Create a new smart contract.
+///
+/// # Arguments
+///
+/// * `name` - name for the smart contract to be created.
+/// * `target` - location where the smart contract will be created.
 pub fn create_smart_contract(name: &str, target: &Path) -> Result<(), Error> {
 	// Canonicalize the target path to ensure consistency and resolve any symbolic links.
 	let canonicalized_path = target

crates/pop-contracts/src/test.rs

@@ -3,6 +3,11 @@ use crate::errors::Error;
 use duct::cmd;
 use std::path::PathBuf;
 
+/// Run unit tests of a smart contract.
+///
+/// # Arguments
+///
+/// * `path` - location of the smart contract.
 pub fn test_smart_contract(path: &Option<PathBuf>) -> Result<(), Error> {
 	// Execute `cargo test` command in the specified directory.
 	cmd("cargo", vec!["test"])
@@ -12,6 +17,11 @@ pub fn test_smart_contract(path: &Option<PathBuf>) -> Result<(), Error> {
 	Ok(())
 }
 
+/// Run the e2e tests of a smart contract.
+///
+/// # Arguments
+///
+/// * `path` - location of the smart contract.
 pub fn test_e2e_smart_contract(path: &Option<PathBuf>) -> Result<(), Error> {
 	// Execute `cargo test --features=e2e-tests` command in the specified directory.
 	cmd("cargo", vec!["test", "--features=e2e-tests"])

crates/pop-contracts/src/up.rs

@@ -14,6 +14,7 @@ use std::path::PathBuf;
 use subxt::PolkadotConfig as DefaultConfig;
 use subxt_signer::sr25519::Keypair;
 
+/// Attributes for the `up` command
 pub struct UpOpts {
 	/// Path to the contract build folder.
 	pub path: Option<PathBuf>,
@@ -35,6 +36,13 @@ pub struct UpOpts {
 	/// Secret key URI for the account deploying the contract.
 	pub suri: String,
 }
+
+/// Prepare `InstantiateExec` data to upload and instantiate a contract.
+///
+/// # Arguments
+///
+/// * `up_opts` - attributes for the `up` command.
+///
 pub async fn set_up_deployment(
 	up_opts: UpOpts,
 ) -> anyhow::Result<InstantiateExec<DefaultConfig, DefaultEnvironment, Keypair>> {
@@ -64,6 +72,12 @@ pub async fn set_up_deployment(
 	return Ok(instantiate_exec);
 }
 
+/// Estimate the gas required for instantiating a contract without modifying the state of the blockchain.
+///
+/// # Arguments
+///
+/// * `instantiate_exec` - the preprocessed data to instantiate a contract.
+///
 pub async fn dry_run_gas_estimate_instantiate(
 	instantiate_exec: &InstantiateExec<DefaultConfig, DefaultEnvironment, Keypair>,
 ) -> anyhow::Result<Weight> {
@@ -89,6 +103,13 @@ pub async fn dry_run_gas_estimate_instantiate(
 	}
 }
 
+/// Instantiate a contract.
+///
+/// # Arguments
+///
+/// * `instantiate_exec` - the preprocessed data to instantiate a contract.
+/// * `gas_limit` - maximum amount of gas to be used for this call.
+///
 pub async fn instantiate_smart_contract(
 	instantiate_exec: InstantiateExec<DefaultConfig, DefaultEnvironment, Keypair>,
 	gas_limit: Weight,

crates/pop-parachains/README.md

@@ -1,11 +1,11 @@
 # pop-parachains
 
-A crate for generating, building and running Parachains and Pallets. 
+A crate for generating, building and running parachains and pallets. Used by
+[`pop-cli`](https://github.com/r0gue-io/pop-cli).
 
-> :information_source: A [crates.io](https://crates.io/crates/pop-parachains) version will be available soon!
 ## Usage
 
-Generate a new Parachain:
+Generate a new parachain:
 ```rust
 use pop_parachains::{instantiate_template_dir, Config, Git, Template};
 

crates/pop-parachains/src/build.rs

@@ -2,6 +2,7 @@
 use duct::cmd;
 use std::path::PathBuf;
 
+/// Build the parachain located in the specified `path`.
 pub fn build_parachain(path: &Option<PathBuf>) -> anyhow::Result<()> {
 	cmd("cargo", vec!["build", "--release"])
 		.dir(path.clone().unwrap_or("./".into()))

crates/pop-parachains/src/lib.rs

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: GPL-3.0
+#![doc = include_str!("../README.md")]
 mod build;
 mod errors;
 mod generator;
@@ -16,5 +17,5 @@ pub use up::{Source, Status, Zombienet};
 pub use utils::git::{Git, GitHub, Release};
 pub use utils::helpers::is_initial_endowment_valid;
 pub use utils::pallet_helpers::resolve_pallet_path;
-// External exports
+/// Information about the Node. External export from Zombienet-SDK.
 pub use zombienet_sdk::NetworkNode;

crates/pop-parachains/src/new_pallet.rs

@@ -10,12 +10,18 @@ use crate::{
 	utils::helpers::sanitize,
 };
 
+/// Metadata for the Template Pallet.
 pub struct TemplatePalletConfig {
 	pub name: String,
 	pub authors: String,
 	pub description: String,
 }
-
+/// Create a new pallet from a template.
+///
+/// # Arguments
+///
+/// * `path` - location where the pallet will be created.
+/// * `config` - customization values to include in the new pallet.
 pub fn create_pallet_template(
 	path: Option<String>,
 	config: TemplatePalletConfig,

crates/pop-parachains/src/new_parachain.rs

@@ -12,7 +12,14 @@ use anyhow::Result;
 use std::{fs, path::Path};
 use walkdir::WalkDir;
 
-/// Creates a new template at `target` dir
+/// Create a new parachain.
+///
+/// # Arguments
+///
+/// * `template` - template to generate the parachain from.
+/// * `target` - location where the parachain will be created.
+/// * `tag_version` - version to use (`None` to use latest).
+/// * `config` - customization values to include in the new parachain.
 pub fn instantiate_template_dir(
 	template: &Template,
 	target: &Path,

crates/pop-parachains/src/templates.rs

@@ -5,6 +5,7 @@ use strum::{
 use strum_macros::{AsRefStr, Display, EnumMessage, EnumProperty, EnumString, VariantArray};
 use thiserror::Error;
 
+/// Supported template providers.
 #[derive(
 	AsRefStr, Clone, Default, Debug, Display, EnumMessage, EnumString, Eq, PartialEq, VariantArray,
 )]
@@ -27,25 +28,30 @@ pub enum Provider {
 }
 
 impl Provider {
+	/// Get the list of providers supported.
 	pub fn providers() -> &'static [Provider] {
 		Provider::VARIANTS
 	}
 
+	/// Get provider's name.
 	pub fn name(&self) -> &str {
 		self.get_message().unwrap_or_default()
 	}
 
+	/// Get the default template of the provider.
 	pub fn default_template(&self) -> Template {
 		match &self {
 			Provider::Pop => Template::Standard,
 			Provider::Parity => Template::ParityContracts,
 		}
 	}
 
+	/// Get the providers detailed description message.
 	pub fn description(&self) -> &str {
 		self.get_detailed_message().unwrap_or_default()
 	}
 
+	/// Get the list of templates of the provider.
 	pub fn templates(&self) -> Vec<&Template> {
 		Template::VARIANTS
 			.iter()
@@ -54,13 +60,15 @@ impl Provider {
 	}
 }
 
+/// Configurable settings for parachain generation.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Config {
 	pub symbol: String,
 	pub decimals: u8,
 	pub initial_endowment: String,
 }
 
+/// Templates supported.
 #[derive(
 	AsRefStr,
 	Clone,
@@ -76,7 +84,7 @@ pub struct Config {
 	VariantArray,
 )]
 pub enum Template {
-	// Pop
+	/// Minimalist parachain template.
 	#[default]
 	#[strum(
 		serialize = "standard",
@@ -89,6 +97,7 @@ pub enum Template {
 		)
 	)]
 	Standard,
+	/// Parachain configured with fungible and non-fungilble asset functionalities.
 	#[strum(
 		serialize = "assets",
 		message = "Assets",
@@ -100,6 +109,7 @@ pub enum Template {
 		)
 	)]
 	Assets,
+	/// Parachain configured to support WebAssembly smart contracts.
 	#[strum(
 		serialize = "contracts",
 		message = "Contracts",
@@ -111,6 +121,7 @@ pub enum Template {
 		)
 	)]
 	Contracts,
+	/// Parachain configured with Frontier, enabling compatibility with the Ethereum Virtual Machine (EVM).
 	#[strum(
 		serialize = "evm",
 		message = "EVM",
@@ -122,7 +133,7 @@ pub enum Template {
 		)
 	)]
 	EVM,
-	// Parity
+	/// Minimal Substrate node configured for smart contracts via pallet-contracts.
 	#[strum(
 		serialize = "cpt",
 		message = "Contracts",
@@ -134,6 +145,7 @@ pub enum Template {
 		)
 	)]
 	ParityContracts,
+	/// Template node for a Frontier (EVM) based parachain.
 	#[strum(
 		serialize = "fpt",
 		message = "EVM",
@@ -148,22 +160,28 @@ pub enum Template {
 }
 
 impl Template {
+	/// Get the template's name.
 	pub fn name(&self) -> &str {
 		self.get_message().unwrap_or_default()
 	}
+
+	/// Get the detailed message of the template.
 	pub fn description(&self) -> &str {
 		self.get_detailed_message().unwrap_or_default()
 	}
 
+	/// Check the template belongs to a `provider`.
 	pub fn matches(&self, provider: &Provider) -> bool {
 		// Match explicitly on provider name (message)
 		self.get_str("Provider") == Some(provider.name())
 	}
 
+	/// Get the template's repository url.
 	pub fn repository_url(&self) -> Result<&str, Error> {
 		self.get_str("Repository").ok_or(Error::RepositoryMissing)
 	}
 
+	/// Get the provider of the template.
 	pub fn provider(&self) -> Result<&str, Error> {
 		self.get_str("Provider").ok_or(Error::ProviderMissing)
 	}