From 9f7ae2ee709ffad1f05176871a550171d7023735 Mon Sep 17 00:00:00 2001
From: bgallois <benjamin@gallois.cc>
Date: Tue, 4 Feb 2025 16:34:12 +0100
Subject: [PATCH] add documentation

---
 xtask/src/gen_doc.rs | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/xtask/src/gen_doc.rs b/xtask/src/gen_doc.rs
index eb5dc2d8..a2eb94a9 100644
--- a/xtask/src/gen_doc.rs
+++ b/xtask/src/gen_doc.rs
@@ -440,6 +440,24 @@ fn get_max_weight_from_metadata_v15(
     }
 }
 
+/// Converts a `Type<PortableForm>` into a human-readable string representation.
+///
+/// This function is a core part of the type resolution pipeline, working together with:
+/// - `resolve_type()` to obtain type definitions.
+/// - `format_generics()` to correctly format generic parameters.
+///
+/// It processes a `Type<PortableForm>` from the metadata registry and outputs a Rust-like string representation,
+/// handling all supported type definitions (composite types, sequences, arrays, tuples, primitives, etc.).
+///
+/// # Returns
+/// - `Ok(String)`: A formatted type string (e.g., `"Vec<u32>"`, `"(i32, bool)"`).
+/// - `Err(anyhow::Error)`: If metadata are incorrect.
+///
+/// # How It Works With Other Functions:
+/// - Calls `format_generics()` to handle generic type parameters.
+/// - Calls `resolve_type()` when resolving inner types inside sequences, arrays, and tuples.
+/// - Used by `resolve_type()` as a formatting step after retrieving a type.
+///
 fn format_type(ty: &Type<PortableForm>, types: &PortableRegistry) -> Result<String> {
     let path = ty.path.to_string();
 
@@ -477,6 +495,16 @@ fn format_type(ty: &Type<PortableForm>, types: &PortableRegistry) -> Result<Stri
     }
 }
 
+/// Resolves a type ID to a formatted string representation.
+///
+/// This function serves as a bridge between raw type IDs and fully formatted types.
+/// It works closely with `format_type()`, ensuring that once a type is found, it is properly formatted.
+///
+/// # How It Works With Other Functions:
+/// - Retrieves a type from the registry using `types.resolve(type_id)`.
+/// - If successful, calls `format_type()` to get a human-readable format.
+/// - Used internally by `format_type()` when resolving type dependencies.
+///
 fn resolve_type(type_id: u32, types: &PortableRegistry) -> Result<String> {
     types
         .resolve(type_id)
@@ -484,6 +512,16 @@ fn resolve_type(type_id: u32, types: &PortableRegistry) -> Result<String> {
         .unwrap_or_else(|| bail!("Invalid metadata"))
 }
 
+/// Formats generic type parameters into a Rust-like string representation.
+///
+/// This function helps `format_type()` handle generic types, ensuring that type parameters
+/// are formatted correctly when they exist. If a type has generic parameters, they are enclosed
+/// in angle brackets (e.g., `<T, U>`).
+///
+/// # How It Works With Other Functions:
+/// - Called inside `format_type()` to process generic type parameters.
+/// - Uses `resolve_type()` to retrieve and format each generic type.
+///
 fn format_generics(
     params: &[scale_info::TypeParameter<PortableForm>],
     types: &PortableRegistry,
@@ -501,6 +539,7 @@ fn format_generics(
         Ok(format!("<{}>", generics.join(", ")))
     }
 }
+
 fn parse_storage_entry(
     variant: &frame_metadata::v15::StorageEntryMetadata<scale_info::form::PortableForm>,
     types: &PortableRegistry,
-- 
GitLab