Improve doc for the System contract

Author: kvinwang

crates/pink/pink-extension/README.md

@@ -34,14 +34,17 @@ fn http_get_example(&self) {
 
 The Pink! crate is designed to empower you, enabling you to leverage the unique features of the Phat Contract, such as making HTTP requests as demonstrated in our examples. This crate supplies the crucial types and functions needed to seamlessly interact with the Phat Contract runtime.
 
-There two kind of APIs to communication with the runtime:
+There are three kind of APIs to communication with the runtime:
 
 -   Emitting Events:
     These APIs are primarily used in situations where the operation could lead to side effects that need to be deterministically recorded and may be rolled back during the execution of the contract call. For additional information on Emitting Events APIs, please refer to the [PinkEvent documentation](crate::PinkEvent).
 
 -   Chain Extension:
     These APIs are predominantly used for read-only operations or operations that aren't expected to create deterministic side effects. For an in-depth understanding of Chain Extension APIs, please refer to the [PinkExt documentation](crate::chain_extension::PinkExtBackend).
 
+-   System contract:
+    There is a special contract called the System contract in each cluster. The system contract is instantiated when the cluster is created. Either ink contracts or external accounts can call the system contract to perform certain operations. For more information on the System contract, please refer to the [System documentation](crate::system::SystemForDoc).
+
 For practical implementation examples, explore our [Phat Contract examples](https://github.com/Phala-Network/phat-contract-examples) repository.
 
 ## Using JavaScript with Phat Contract

crates/pink/pink-extension/macro/src/driver_system.rs

@@ -1,6 +1,6 @@
 use proc_macro2::{Ident, Span, TokenStream as TokenStream2};
 use quote::quote;
-use syn::{spanned::Spanned, FnArg, Result};
+use syn::{parse_quote, spanned::Spanned, FnArg, Result};
 
 pub(crate) enum InterfaceType {
     System,
@@ -25,6 +25,8 @@ fn patch_or_err(
 ) -> Result<TokenStream2> {
     use heck::{ToLowerCamelCase, ToSnakeCase};
     let the_trait: syn::ItemTrait = syn::parse2(input)?;
+    let trait_for_doc = generate_trait_for_doc(the_trait.clone());
+    let the_trait = patch_origin_system_doc(the_trait);
     let trait_ident = &the_trait.ident;
     let trait_name = the_trait.ident.to_string();
     let trait_impl_mod = Ident::new(
@@ -133,6 +135,9 @@ fn patch_or_err(
         #config
         #the_trait
 
+        #[cfg(doc)]
+        #trait_for_doc
+
         pub use #trait_impl_mod::#impl_type;
         mod #trait_impl_mod {
             use super::*;
@@ -223,6 +228,38 @@ fn patch_or_err(
     })
 }
 
+fn patch_origin_system_doc(mut trait_item: syn::ItemTrait) -> syn::ItemTrait {
+    let additonal_doc = format!(
+        "**The doc is messed up by the ink macro. See [`{}ForDoc`] for a clean version**\n\n",
+        trait_item.ident
+    );
+    trait_item
+        .attrs
+        .insert(0, parse_quote!(#[doc = #additonal_doc]));
+    trait_item
+}
+
+fn generate_trait_for_doc(mut trait_item: syn::ItemTrait) -> syn::ItemTrait {
+    let additonal_doc = format!(
+        "**This is the clean version doc of [`{}`]**\n\n",
+        trait_item.ident
+    );
+    trait_item.attrs.retain(|attr| attr.path().is_ident("doc"));
+    trait_item
+        .attrs
+        .insert(0, parse_quote!(#[doc = #additonal_doc]));
+    trait_item.ident = syn::Ident::new(
+        &format!("{}ForDoc", trait_item.ident),
+        trait_item.ident.span(),
+    );
+    for item in trait_item.items.iter_mut() {
+        if let syn::TraitItem::Fn(method) = item {
+            method.attrs.retain(|attr| !attr.path().is_ident("ink"));
+        }
+    }
+    trait_item
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/pink/pink-extension/src/chain_extension/http_request.rs

@@ -12,6 +12,23 @@ pub struct HttpRequest {
     pub body: Vec<u8>,
 }
 
+impl HttpRequest {
+    /// Create a new http request.
+    pub fn new(
+        url: impl Into<String>,
+        method: impl Into<String>,
+        headers: Vec<(String, String)>,
+        body: Vec<u8>,
+    ) -> Self {
+        Self {
+            url: url.into(),
+            method: method.into(),
+            headers,
+            body,
+        }
+    }
+}
+
 #[derive(scale::Encode, scale::Decode)]
 #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
 pub struct HttpResponse {

crates/pink/pink-extension/src/system.rs

@@ -41,52 +41,65 @@ pub use this_crate::VersionTuple;
 
 /// The pink system contract interface.
 ///
-/// A system contract would be instantiated whenever a cluster is created.
+/// The system contract, instantiated with each cluster creation, manages access permissions to
+/// the privileged chain extension functions and pink events. Some of these functions or events
+/// are exclusive to the system contract. User contracts wishing to call these functions or
+/// emit these events must first request the system contract, which then checks the permissions
+/// to either execute or reject the request.
 #[pink::system]
 #[ink::trait_definition(namespace = "pink_system")]
 pub trait System {
-    /// The version of the system. Can be used to determine the api ability.
+    /// Returns the system contract version, indicating its API capabilities.
+    ///
+    /// # Example
+    /// ```no_run
+    /// use pink_extension::system::SystemRef;
+    /// let (major, minor, patch) = SystemRef::instance().version();
+    /// ```
     #[ink(message, selector = 0x87c98a8d)]
     fn version(&self) -> VersionTuple;
-    /// Grant an address the administrator role.
+
+    /// Grants the administrator role to an address. Administrator contracts can set drivers,
+    /// deploy sidevm, etc.
     ///
-    /// The caller must be the owner of the cluster.
+    /// Must be called by the cluster owner.
     #[ink(message)]
     fn grant_admin(&mut self, contract_id: AccountId) -> Result<()>;
 
-    /// Check if an address is an administrator
+    /// Checks if an address is an administrator.
     #[ink(message)]
     fn is_admin(&self, contract_id: AccountId) -> bool;
 
-    /// Set a contract as a driver for `name`.
+    /// Marks a contract as a driver for a given name, retrievable via `get_driver` or `get_driver2`.
+    /// The caller must be the cluster owner or an administrator. Any valid string can be a name.
+    /// There are predefined names used by the Phat Contract system.
     ///
-    /// The caller must be the owner of the cluster or an administrator.
+    /// There are some predefined names that are used by the Phat Contract system:
+    /// - `PinkLogger`: The contract that with a sidevm instance that collect the logs and events
+    ///  emitted by the ink! contracts in current cluster.
+    /// - `ContractDeposit`: The contract that implements the `trait ContractDeposit` which talks
+    ///  to the pallet PhatKokenomic on Phala chain.
     #[ink(message)]
     fn set_driver(&mut self, name: String, contract_id: AccountId) -> Result<()>;
 
-    /// Get driver contract id for `name`.
+    /// Retrieves the driver contract id for a given name.
     #[ink(message)]
     fn get_driver(&self, name: String) -> Option<AccountId>;
 
-    /// Get driver contract id for `name` and the set block number.
+    /// Retrieves the driver contract id and the set block number for a given name.
     #[ink(message)]
     fn get_driver2(&self, name: String) -> Option<(crate::BlockNumber, AccountId)>;
 
-    /// Deploy a sidevm instance attached to a given contract.
-    ///
-    /// The caller must be an administrator.
+    /// Deploys a sidevm instance attached to a contract. Must be called by an administrator.
     #[ink(message)]
     fn deploy_sidevm_to(&self, contract_id: AccountId, code_hash: Hash) -> Result<()>;
 
-    /// Stop a sidevm instance attached to a given contract.
-    ///
-    /// The caller must be an administrator.
+    /// Stops a sidevm instance attached to a contract. Must be called by an administrator.
     #[ink(message)]
     fn stop_sidevm_at(&self, contract_id: AccountId) -> Result<()>;
 
-    /// Set block hook, such as OnBlockEnd, for given contract
-    ///
-    /// The caller must be an administrator.
+    /// Sets a block hook for a contract. Must be called by an administrator.
+    /// Note: This feature is deprecated and will be removed in the future.
     #[ink(message)]
     fn set_hook(
         &mut self,
@@ -96,44 +109,43 @@ pub trait System {
         gas_limit: u64,
     ) -> Result<()>;
 
-    /// Set weight of the contract for query requests and sidevm scheduling.
-    ///
-    /// Higher weight would let the contract to get more resource.
+    /// Sets the contract weight for query requests and sidevm scheduling.
+    /// A higher weight allows the contract to access more resources.
     #[ink(message)]
     fn set_contract_weight(&self, contract_id: AccountId, weight: u32) -> Result<()>;
 
-    /// Return the total balance of given account
+    /// Returns the total balance of a given account.
     #[ink(message)]
     fn total_balance_of(&self, account: AccountId) -> Balance;
 
-    /// Return the free balance of given account
+    /// Returns the free balance of a given account.
     #[ink(message)]
     fn free_balance_of(&self, account: AccountId) -> Balance;
 
-    /// Upgrade the system contract to the latest version.
+    /// Upgrades the system contract to the latest version.
     #[ink(message)]
     fn upgrade_system_contract(&mut self) -> Result<()>;
 
-    /// Do the upgrade condition checks and state migration if necessary.
-    ///
-    /// This function is called by the system contract itself on the new version
-    /// of code in the upgrading process.
+    /// Performs upgrade condition checks and state migration if necessary.
+    /// Called by the system contract on the new code version during an upgrade process.
     #[ink(message)]
     fn do_upgrade(&self, from_version: VersionTuple) -> Result<()>;
 
-    /// Upgrade the contract runtime
+    /// Upgrades the contract runtime.
     #[ink(message)]
     fn upgrade_runtime(&mut self, version: (u32, u32)) -> Result<()>;
 
-    /// Check if the code is already uploaded to the cluster with given code hash.
+    /// Checks if the code with a given hash is already uploaded to the cluster.
     #[ink(message)]
     fn code_exists(&self, code_hash: Hash, code_type: CodeType) -> bool;
 
-    /// Get the current code hash of given contract.
+    /// Retrieves the current code hash of a given contract.
     #[ink(message)]
     fn code_hash(&self, account: AccountId) -> Option<ink::primitives::Hash>;
 
-    /// Get the history of given driver.
+    /// Retrieves the history of a given driver, returning a vector of
+    /// (block_number, contract_id) tuples where the block number is the
+    /// block number when the driver is set.
     #[ink(message)]
     fn driver_history(&self, name: String) -> Option<Vec<(crate::BlockNumber, AccountId)>>;
 }