Add docs for docs.rs

Signed-off-by: Keshav Priyadarshi <[email protected]>

Author: keshav-space

src/lib.rs

@@ -9,6 +9,24 @@ See https://aboutcode.org for more information about nexB OSS projects.
 
 */
 
+//! A library to validate whether a PURL actually exists.
+//!
+//! **purl-validator** is a Rust library for validating
+//! [`Package URLs` (PURLs)](https://github.com/package-url/purl-spec).
+//! It works fully offline, including in **air-gapped** or **restricted environments**,
+//! and answers one key question: **Does the package this PURL represents actually exist?**
+//!
+//!
+//! # Examples
+//!
+//! Simplest way to use `validate` is as follows:
+//!
+//! ```
+//! use purl_validator::validate;
+//!
+//! let result: bool = validate("pkg:nuget/FluentValidation");
+//! ```
+//!
 
 use fst::Set;
 use memmap2::Mmap;
@@ -28,9 +46,20 @@ fn load_fst(path: &Path) -> Set<Mmap> {
     Set::new(mmap).expect("Failed to load FST from mmap")
 }
 
-pub fn validate(packageurl: &str) -> bool {
+fn strip_and_check_purl(packageurl: &str, fst_map: &Set<Mmap>) -> bool {
     let trimmed_packageurl = packageurl.trim_end_matches("/");
-    VALIDATOR.contains(trimmed_packageurl)
+    fst_map.contains(trimmed_packageurl)
+}
+
+/// Validate a Package URL (PURL)
+///
+/// Returns `true` if the given base PURL represents an existing package,
+/// otherwise returns `false`.
+///
+/// Use pre-built FST (Finite State Transducer) to perform lookups and confirm whether
+/// the **base PURL** exists.
+pub fn validate(packageurl: &str) -> bool {
+    strip_and_check_purl(packageurl, &VALIDATOR)
 }
 
 #[cfg(test)]