From ccfd443e5d089b48e494abc2163d9c5843a1cf92 Mon Sep 17 00:00:00 2001
From: Wataru Otsubo <wotsubo@icepp.s.u-tokyo.ac.jp>
Date: Mon, 31 Mar 2025 17:53:44 +0900
Subject: [PATCH] update(docs): add docs on validator

---
 src/lib.rs       | 4 +++-
 src/main.rs      | 2 ++
 src/validator.rs | 2 ++
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/lib.rs b/src/lib.rs
index 483816a..113906c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -14,7 +14,8 @@
 //!
 //! 1. Convert [`roxmltree::Document`] to register map represented with types defined in
 //!    [`types`], filling missing parameters. See [`converter`].
-//! 2. Generate [`proc_macro2::TokenStream`] from register map produced in the previous step. See
+//! 2. Validate the register map. See [`types::Module::validate`] in [`validator`].
+//! 3. Generate [`proc_macro2::TokenStream`] from register map produced in the previous step. See
 //!    [`generator`].
 //!
 //! # modules
@@ -22,6 +23,7 @@
 //! - [`converter`]: DOM to internal representation
 //! - [`generator`]: internal representation to rust code
 //! - [`io`]: formatting and printing
+//! - [`validator`]: validate the register map and generate flattened register map
 
 pub mod converter;
 pub mod generator;
diff --git a/src/main.rs b/src/main.rs
index 49d2788..01ca8e7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -16,6 +16,8 @@ struct Args {
 #[derive(Debug, Subcommand)]
 enum Commands {
     /// Generate register interface code.
+    ///
+    /// Also run validation before generation.
     Generate {
         /// Output directory.
         out: path::PathBuf,
diff --git a/src/validator.rs b/src/validator.rs
index 9b92338..17a379e 100644
--- a/src/validator.rs
+++ b/src/validator.rs
@@ -20,6 +20,8 @@ type FlattenedRegisterMap<'a> = Vec<Option<FlattenedRegisterEntry<'a>>>;
 
 impl Module {
     /// Validate the address assignment, generating a flatten register map.
+    /// Returns a tuple of [`FlattenedRegisterMap`] and [`ValidationError`]s vector.
+    /// Empty errors vector means there is no errors in the register map.
     pub fn validate(&self) -> (FlattenedRegisterMap, Vec<ValidationError>) {
         let mut mapping = Vec::new();
         mapping.resize(self.size.try_into().unwrap(), None);