add some docs

check.sh

@@ -12,7 +12,7 @@ if [[ -n ${ldd} ]]; then
 fi
 
 if [[ ! -d build ]]; then
-    meson setup -Dfuzz=enabled -Dtests=enabled -Dbuildtype=debugoptimized build || exit $?
+    meson setup -Dfuzz=enabled -Dtests=enabled -Dbuildtype=debugoptimized -Ddocs=enabled build || exit $?
 fi
 
 meson compile -C build || exit $?

check_commands.txt

@@ -1,4 +1,5 @@
 /usr/bin/meson format --recursive --check-only
 rustfmt --edition 2024 --check $(find src -type f -name '*.rs')
+ninja rustdoc -C build
 ninja clippy -C build
-meson test unittests '*repo*' '*porthole*' -C build
+meson test unittests doctests '*repo*' '*porthole*' -C build

meson.build

@@ -28,3 +28,13 @@ endif
 if get_option('fuzz').enabled()
     subdir('fuzz')
 endif
+
+if get_option('docs').enabled()
+    rust.doctest(
+        'doctests',
+        gentoo_utils,
+        dependencies: [mon, get, itertools],
+        link_with: [thiserror],
+        args: ['--nocapture'],
+    )
+endif

meson.options

@@ -1,2 +1,3 @@
 option('fuzz', type: 'feature', value: 'disabled')
 option('tests', type: 'feature', value: 'disabled')
+option('docs', type: 'feature', value: 'disabled')

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;