From 40e06b7566543f724d998b7a000a950b89004da2 Mon Sep 17 00:00:00 2001
From: Mollemoll <jonas.molander@gmail.com>
Date: Tue, 14 May 2024 15:07:54 +0200
Subject: [PATCH] docs: initial inline documentation

---
 src/errors.rs       |  2 ++
 src/lib.rs          | 34 ++++++++++++++++++++++++++++++++++
 src/verification.rs | 18 ++++++++++++++++++
 3 files changed, 54 insertions(+)

diff --git a/src/errors.rs b/src/errors.rs
index 55240e8..96875a4 100644
--- a/src/errors.rs
+++ b/src/errors.rs
@@ -4,9 +4,11 @@ use std::fmt::Debug;
 #[derive(thiserror::Error, Debug, PartialEq)]
 pub enum ValidationError {
     #[error("Country code {0} is not supported")]
+    /// The country code is not supported
     UnsupportedCountryCode(String),
 
     #[error("Invalid syntax")]
+    /// The syntax of the tax id is invalid for the given country
     InvalidSyntax,
 }
 
diff --git a/src/lib.rs b/src/lib.rs
index 886f507..c65aef2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,19 @@
+//! This Rust crate provides a solution for verifying tax ids (VAT/GST) for businesses operating
+//! within the European Union, the United Kingdom, Switzerland, and Norway.
+//!
+//! ### Features
+//!
+//! - **Country-Specific Syntax Validation**: The library includes functionality to validate the syntax
+//!   of tax ids based on the specific rules and formats of each supported country.
+//!
+//! - **Verification Requests**: Beyond simple syntax validation, this library can perform actual
+//!   verification requests against the appropriate government databases. This allows for real-time
+//!   confirmation or denial of the legitimacy of a given tax id.
+//!
+//! The library has been inspired by the [valvat] library for Ruby.
+//!
+//! [valvat]: https://github.com/yolk/valvat
+
 mod errors;
 mod verification;
 mod syntax;
@@ -66,6 +82,8 @@ impl fmt::Debug for TaxId {
 }
 
 impl TaxId {
+    /// Use this associated function to validate the syntax of a given tax id number against
+    /// its country-specific regex pattern without creating any TaxId.
     pub fn validate_syntax(value: &str) -> Result<(), ValidationError> {
         let tax_country_code = &value[0..2];
         SYNTAX.get(tax_country_code)
@@ -79,6 +97,9 @@ impl TaxId {
             })
     }
 
+    /// Constructs a TaxId after validating its syntax based on the country-specific regex pattern.
+    /// If the syntax validation is successful, the returned TaxId can be used for further
+    /// verification against the corresponding government database.
     pub fn new(value: &str) -> Result<TaxId, ValidationError> {
         let tax_country_code = &value[0..2];
         let local_value = &value[2..];
@@ -106,15 +127,28 @@ impl TaxId {
         })
     }
 
+    /// Performs a request to verify the tax id against the corresponding government database.
     pub fn verify(&self) -> Result<Verification, VerificationError> {
         self.id_type.verifier().verify(self)
     }
 
+    /// Returns the full tax id value. IE: SE556703748501
     pub fn value(&self) -> &str { &self.value }
+    /// Returns the country code. IE: SE
     pub fn country_code(&self) -> &str { &self.country_code }
+    /// Returns the tax country code. IE: SE
+    ///
+    /// This is the same as the country code for most countries, but not for XI and EL.
+    ///
+    /// XI is the tax country code that Northern Ireland business (the United Kingdom) should use
+    /// while trading with the EU. A consequence of Brexit.
+    ///
+    /// EL is the tax country code for Greece.
     pub fn tax_country_code(&self) -> &str { &self.tax_country_code }
+    /// Returns the local value of the tax id. IE: 556703748501
     pub fn local_value(&self) -> &str { &self.local_value }
 
+    /// Returns the type of tax id in snake_case. IE: eu_vat, gb_vat, ch_va or no_vat
     pub fn tax_id_type(&self) -> &str { self.id_type.name() }
     fn id_type(&self) -> &Box<dyn TaxIdType> { &self.id_type }
 }
diff --git a/src/verification.rs b/src/verification.rs
index b447940..6af33bf 100644
--- a/src/verification.rs
+++ b/src/verification.rs
@@ -22,8 +22,11 @@ impl VerificationResponse {
 
 #[derive(Debug, PartialEq)]
 pub enum VerificationStatus {
+    /// Represents a successful verification where the government database confirmed the ID as legitimate.
     Verified,
+    /// Represents an unsuccessful verification where the government database identified the ID as illegitimate.
     Unverified,
+    /// Represents a case where verification was not possible due to certain reasons (e.g., government database was unavailable).
     Unavailable,
 }
 
@@ -35,6 +38,7 @@ pub struct Verification {
 }
 
 impl Verification {
+    #[doc(hidden)]
     pub fn new(status: VerificationStatus, data: serde_json::Value) -> Verification {
         Verification {
             performed_at: Local::now(),
@@ -43,7 +47,21 @@ impl Verification {
         }
     }
 
+    /// This VerificationStatus is what the crate user should use to determine how to proceed.
+    ///
+    /// A checkout example:
+    /// - Enable/process the transaction upon `VerificationStatus::Verified`.
+    /// - Block transaction/provide a validation msg upon `VerificationStatus::Unverified`.
+    /// - Enable/process the transaction upon `VerificationStatus::Unavailable` but perform a
+    ///     re-verification at a later stage.
     pub fn status(&self) -> &VerificationStatus { &self.status }
+    /// Additional data selected by the crate owner from the government database response.
+    /// This data can be used to provide more context about the verification.
+    /// The data is in JSON format.
+    ///
+    /// Includes error details in case of an unsuccessful verification.
+    ///
+    /// Subject to change in future versions.
     pub fn data(&self) -> &serde_json::Value { &self.data }
 }