From 4673824f436e02a2a498da9d3f2a0542eb01a118 Mon Sep 17 00:00:00 2001
From: Owen Troke-Billard <owen.trokebillard@outlook.com>
Date: Mon, 16 Sep 2024 15:11:00 -0600
Subject: [PATCH] Add crate documentation

---
 src/builder.rs |  2 +-
 src/graph.rs   |  2 +-
 src/iter.rs    |  3 +++
 src/lib.rs     | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/src/builder.rs b/src/builder.rs
index d602a90..4b65c90 100644
--- a/src/builder.rs
+++ b/src/builder.rs
@@ -64,7 +64,7 @@ where
     DefaultVf2Builder::new(Problem::InducedSubgraphIsomorphism, query, data)
 }
 
-/// A VF2 builder.
+/// A VF2 builder used to configure the algorithm.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct Vf2Builder<'a, Query, Data, NodeEq, EdgeEq> {
     /// Problem type.
diff --git a/src/graph.rs b/src/graph.rs
index a6c6264..bea9a82 100644
--- a/src/graph.rs
+++ b/src/graph.rs
@@ -38,7 +38,7 @@ pub trait Graph {
 /// A node index.
 pub type NodeIndex = usize;
 
-/// Edge direction.
+/// Edge direction, either outgoing or incoming.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum Direction {
     Outgoing,
diff --git a/src/iter.rs b/src/iter.rs
index c51b55b..3261249 100644
--- a/src/iter.rs
+++ b/src/iter.rs
@@ -3,6 +3,9 @@ use crate::{Graph, Isomorphism};
 use std::fmt::Debug;
 
 /// An isomorphism iterator.
+///
+/// This traverses the state space representation and yields
+/// isomorphisms as they are found.
 #[derive(Clone, Debug)]
 pub struct IsomorphismIter<'a, Query, Data, NodeEq, EdgeEq> {
     state: State<'a, Query, Data, NodeEq, EdgeEq>,
diff --git a/src/lib.rs b/src/lib.rs
index 6d5c65c..f46032b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,65 @@
+//! This crate implements the VF2 subgraph isomorphism algorithm.
+//! It can find
+//! [graph isomorphisms](https://en.wikipedia.org/wiki/Graph_isomorphism),
+//! [subgraph isomorphisms](https://en.wikipedia.org/wiki/Subgraph_isomorphism_problem),
+//! and [induced subgraph isomorphisms](https://en.wikipedia.org/wiki/Induced_subgraph_isomorphism_problem).
+//! Graphs can be directed or undirected.
+//!
+//! See the [repository](https://github.com/OwenTrokeBillard/vf2) for more information.
+//!
+//! # Instructions
+//!
+//! Create your query and data graphs with [petgraph](https://github.com/petgraph/petgraph)
+//! or any library that implements the [Graph] trait. Then, call one of the following
+//! functions based on the problem type:
+//! - Graph isomorphisms: [`isomorphisms`].
+//! - Subgraph isomorphisms: [`subgraph_isomorphisms`].
+//! - Induced subgraph isomorphisms: [`induced_subgraph_isomorphisms`].
+//!
+//! These return a [`Vf2Builder`] with the algorithm configured.
+//! Next, call one of the following to enumerate the isomorphisms:
+//! - First isomorphism: [`first`](Vf2Builder::first).
+//! - Vector of isomorphisms: [`vec`](Vf2Builder::vec).
+//! - Iterator of isomorphisms: [`iter`](Vf2Builder::iter).
+//!
+//! Filling a vector can consume a significant amount of memory.
+//! Use the iterator to inspect isomorphisms as they are found.
+//! For even better performance, call [`next_ref`](IsomorphismIter::next_ref)
+//! to avoid cloning each isomorphism.
+//!
+//! You can configure the node and edge equality functions on the builder
+//! with [`node_eq`](Vf2Builder::node_eq) and [`edge_eq`](Vf2Builder::edge_eq),
+//! respectively.
+//!
+//! # Example
+//!
+//! This example shows how to find subgraph isomorphisms.
+//!
+//! ```
+//! use petgraph::data::{Element, FromElements};
+//! use petgraph::graph::DiGraph;
+//!
+//! // Create query graph.
+//! let query = DiGraph::<i32, ()>::from_elements([
+//!     Element::Node { weight: 0, },
+//!     Element::Node { weight: 1, },
+//!     Element::Edge { source: 0, target: 1, weight: () },
+//! ]);
+//!
+//! // Create data graph.
+//! let data = DiGraph::<i32, ()>::from_elements([
+//!     Element::Node { weight: 0, },
+//!     Element::Node { weight: 1, },
+//!     Element::Node { weight: 2, },
+//!     Element::Edge { source: 0, target: 1, weight: () },
+//!     Element::Edge { source: 1, target: 2, weight: () },
+//! ]);
+//!
+//! // Find subgraph isomorphisms.
+//! let isomorphisms = vf2::subgraph_isomorphisms(&query, &data).vec();
+//! assert_eq!(isomorphisms, vec![vec![0, 1], vec![1, 2]]);
+//! ```
+
 mod builder;
 mod graph;
 mod isomorphism;