From abf784a784c6e9282dbfbe269670da0284556a7d Mon Sep 17 00:00:00 2001
From: John Turner <jturner.usa@gmail.com>
Date: Sun, 30 Nov 2025 22:12:49 +0000
Subject: add some docs

---
 src/lib.rs | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

(limited to 'src/lib.rs')

diff --git a/src/lib.rs b/src/lib.rs
index beeae1e..7cef9a8 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,17 @@
+//! Gentoo and PMS related utils.
+//!
+//! Currently implements:
+//! - parsers for atoms and DEPEND expressions
+//! - strongly typed representations of atoms, versions, etc
+//! - version comparison and equality impls
+//! - iterator over repos categories and ebuilds
+//!
+//! Planned features
+//! - profile evaluation
+//! - vdb reader
+//! - sourcing ebuilds with bash
+//!
+
 #![deny(clippy::pedantic, unused_imports)]
 #![allow(
     dead_code,
@@ -15,6 +29,58 @@ pub trait Parseable<'a, I: Input + 'a> {
     fn parser() -> Self::Parser;
 }
 
+/// Strongly typed atom and cpv representations.
+///
+/// Create atoms from parsers:
+/// ```
+/// use gentoo_utils::{Parseable, atom::Atom};
+/// use mon::{Parser, input::InputIter};
+///
+/// let it = InputIter::new("=app-editors/emacs-31.0-r1");
+/// let emacs = Atom::parser().parse_finished(it).unwrap();
+///
+/// assert_eq!(emacs.to_string(), "=app-editors/emacs-31.0-r1");
+/// ````
+///
+/// Compare versions:
+/// ```
+/// use gentoo_utils::{Parseable, atom::Cpv};
+/// use mon::{Parser, input::InputIter};
+///
+/// let a = Cpv::parser()
+///     .parse_finished(InputIter::new("foo/bar-1.0"))
+///     .unwrap();
+///
+/// let b = Cpv::parser()
+///     .parse_finished(InputIter::new("foo/bar-2.0"))
+///     .unwrap();
+///
+/// assert!(a < b);
+/// ```
 pub mod atom;
+
+/// Access to repos and ebuilds.
+///
+/// ```
+/// use gentoo_utils::repo::Repo;
+///
+/// let repo = Repo::new("/var/db/repos/gentoo");
+///
+/// for result in repo.categories().expect("failed to read categories") {
+///    let category = result.expect("failed to read category");
+///
+///    for result in category.ebuilds().expect("failed to read ebuilds") {
+///        let ebuild = result.expect("failed to read ebuild");
+///
+///        println!(
+///            "{}-{}: {}",
+///            ebuild.name(),
+///            ebuild.version(),
+///            ebuild.description().clone().unwrap_or("no description available".to_string())
+///        );
+///    }
+/// }
+///
+/// ```
 pub mod repo;
 pub mod useflag;
-- 
cgit v1.2.3