Add commemts

Author: febo

include-idl-cli/src/main.rs

@@ -1,9 +1,6 @@
-use std::path::PathBuf;
-
-// use goblin::error::Result;
-use include_idl::parse::parse_idl_from_program_binary;
-
 use clap::{Error, Parser, Subcommand};
+use include_idl::parse::parse_idl_from_program_binary;
+use std::path::PathBuf;
 
 #[derive(Parser)]
 #[command(version, about, long_about = None)]

include-idl/Cargo.toml

@@ -3,8 +3,6 @@ name = "include-idl"
 version = "0.1.0"
 edition = "2021"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [features]
 shrink = ["flate2"]
 parse = ["flate2", "goblin", "serde_json"]

include-idl/src/lib.rs

@@ -1,3 +1,5 @@
+//! This crate provides a way to include IDL files in a program binary.
+
 pub mod parse;
 
 #[cfg(feature = "shrink")]
@@ -6,6 +8,29 @@ mod shrink;
 #[cfg(feature = "shrink")]
 pub use shrink::compress_idl;
 
+/// Include an IDL file in the program binary.
+///
+/// This macro creates two ELF sections in the program binary:
+/// - `.idl.type` contains the type of the IDL file.
+/// - `.idl.data` contains the IDL file itself.
+///
+/// In general you should use this macro in conbination with a `build.rs` build script
+/// that compresses the IDL file to reduce the final size of the program binary.
+///
+/// # Arguments
+///
+/// This macro takes two arguments:
+///
+/// - `type`: The type of the IDL file. This should be one of the variants of the [`IdlType``] enum.
+/// - `file`: The path to the IDL file.
+///
+/// # Example
+///
+/// Include the following in your `lib.rs` file:
+///
+/// ```ignore
+/// include_idl!(IdlType::Codama, concat!(env!("OUT_DIR"), "/codama.idl.zip"));
+/// ```
 #[macro_export]
 macro_rules! include_idl {
     ($type:path, $file:expr) => {

include-idl/src/parse.rs

@@ -13,7 +13,10 @@ pub const IDL_TYPE_SECTION: &str = ".idl.type";
 /// Name of the section containing the IDL data.
 pub const IDL_DATA_SECTION: &str = ".idl.data";
 
+/// `str` representation of the Anchor IDL type.
 const ANCHOR_IDL_TYPE: &str = "anchor";
+
+/// `str` representation of the Codama IDL type.
 const CODAMA_IDL_TYPE: &str = "codama";
 
 /// Defines the IDL type.
@@ -53,6 +56,7 @@ impl std::str::FromStr for IdlType {
     }
 }
 
+/// Parses the IDL data from the program binary.
 #[cfg(feature = "parse")]
 pub fn parse_idl_from_program_binary(buffer: &[u8]) -> goblin::error::Result<(IdlType, Value)> {
     let elf = Elf::parse(buffer)?;
@@ -97,6 +101,7 @@ pub fn parse_idl_from_program_binary(buffer: &[u8]) -> goblin::error::Result<(Id
     }
 }
 
+/// Retrieves the location and size of an ELF section data.
 #[cfg(feature = "parse")]
 #[inline(always)]
 fn get_section_data_offset(buffer: &[u8], offset: usize) -> (usize, usize) {

include-idl/src/shrink.rs

@@ -1,30 +1,27 @@
-#[cfg(feature = "shrink")]
+use flate2::{write::ZlibEncoder, Compression};
 use std::{
     fs::File,
     io::{Read, Write},
     path::PathBuf,
 };
 
-#[cfg(feature = "shrink")]
-use flate2::{write::ZlibEncoder, Compression};
-
-#[cfg(feature = "shrink")]
+/// Compresses the IDL JSON file using zlib and writes the compressed data to a file.
 pub fn compress_idl(idl_path: &PathBuf, dest_path: &PathBuf) {
     let mut idl_json = File::open(idl_path).unwrap();
     let mut json_contents = String::new();
     idl_json
         .read_to_string(&mut json_contents)
         .expect("Failed to read JSON file");
 
-    // Compress the JSON contents using zlib
+    // Compress the JSON contents using zlib.
     let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
     encoder
         .write_all(json_contents.as_bytes())
         .expect("Failed to compress JSON data");
     let compressed_data = encoder.finish().expect("Failed to finish compression");
 
-    // Get the output directory for the build script
-    // Write the compressed data to a file in the output directory
+    // Get the output directory for the build script and write the compressed
+    // data to a file in the output directory.
     let mut output_file = File::create(dest_path).expect("Failed to create output file");
     output_file
         .write_all(&compressed_data)