Crate documentation

.github/workflows/main.yml

@@ -54,6 +54,18 @@ jobs:
         run: cargo check
         working-directory: fuzz
 
+  check-doc:
+    name: Rustdoc check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Cargo doc
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --no-deps --document-private-items --workspace
+
   test:
     name: Test (${{ matrix.rust }})
     runs-on: ubuntu-latest

DESIGN.md

@@ -343,8 +343,8 @@ Iterative traversals are preferred over recursive traversals. The main advantage
 is that iterative traversals are lazy, thus allowing to stop the traversal
 without "hacking" the control flow semantics into callback's return type, and
 can be "detached" from the graph so that the graph can be manipulated during
-traversal (:handshake: :hammer:). Iterative traversal is also not limited by the
-size of the program stack. However, in some cases this choice imposes an
+traversal ( :handshake: :hammer: ). Iterative traversal is also not limited by
+the size of the program stack. However, in some cases this choice imposes an
 efficiency penalty. See implementation of `RawDfsExtra` for the most notable
 example.
 

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# gryf
+<img src="https://raw.githubusercontent.com/pnevyk/gryf/main/assets/logo-gryf-text.png" width="400px" />
 
 > Graph data structure library aspiring to be convenient, versatile, correct and performant.
 
@@ -34,10 +34,12 @@ fn main() {
 
     graph.extend_with_edges([
         (prague, bratislava, 328u32),
-        (prague, nuremberg, 293),
+        (prague, nuremberg, 297),
+        (prague, vienna, 293),
         (bratislava, vienna, 79),
         (nuremberg, munich, 170),
         (vienna, munich, 402),
+        (vienna, florence, 863),
         (munich, florence, 646),
         (florence, rome, 278),
     ]);
@@ -53,43 +55,38 @@ fn main() {
         .join(" - ");
 
     println!("{distance} km from Prague through {path}");
-    // 1387 km from Prague through Nuremberg - Munich - Florence - Rome
+    // 1391 km from Prague through Nuremberg - Munich - Florence - Rome
 }
 ```
 
-## Overview
+##  Goals
 
-The main goal of gryf is to be
+The main goals of gryf are to be
 
-* **convenient** -- "make the common case straightforward and natural<sup>1</sup>",
-* **versatile** -- "offer simplicity as well as flexibility and strive for a
-  good balance if in conflict",
-* **correct** -- "use extensive fuzzing and property-based testing to increase
-  confidence about correctness", and
-* **performant** -- "write the code with performance and memory efficiency in
-  mind".
+* _convenient_, that is, "making the common case straightforward and natural",
+* _versatile_, that is, "offering simplicity as well as flexibility and striving
+  for a good balance if in conflict",
+* _correct_, that is, "using extensive fuzzing and property-based testing to
+  increase confidence about correctness", and
+* _performant_, that is, "writing the code with performance and memory
+  efficiency in mind".
 
-The algorithms are [organized into the
-problems](#problems-instead-of-algorithms) they solve. For specifying the
-options of an algorithm the [builder pattern](#builder-pattern-for-algorithms)
-is utilized. Graphs can use different storage [under the
-hood](#separation-of-graph-storage-and-semantics).
+Failing in any of these should be considered an issue to be reported.
 
-<sup>1</sup>Failing in this should be considered a bug and reported.
-
-## Details
+## Design
 
 _For more details, see the [design doc](./DESIGN.md)._
 
 ### Problems instead of algorithms
 
-For users without much experience or knowledge in graph theory and algorithms,
-it may not be obvious which algorithm should (or even can) be used to solve the
-given problem at hand. Instead, gryf organizes the algorithms into the problem
-they solve (e.g., `ShortestPaths`) instead of exposing the algorithms directly
-(`dijkstra`, `bellman_ford`).
+It may not be obvious which algorithm should (or even can) be used to solve the
+given problem at hand, especially for users without much experience or knowledge
+in graph theory and algorithms. Instead, gryf organizes the algorithms into the
+problem they solve (e.g., `ShortestPaths`) instead of requiring to call the
+algorithms directly (`dijkstra`, `bellman_ford`).
 
-This brings a number of benefits, among which the most important are:
+Organizing algorithms into problems brings a number of benefits, among which the
+most important are:
 
 * It is convenient for the user, especially if they are a beginner. It allows
   them not to care about details if they don't want to care.
@@ -107,7 +104,7 @@ let shortest_paths = ShortestPaths::on(&graph).run(rome).unwrap();
 ### Builder pattern for algorithms
 
 Specifying arguments for algorithms is done using the builder pattern. This
-avoids the need of passing dummy values (like `None`) to parameters that are not
+avoids the need to pass dummy values (like `None`) to parameters that are not
 useful for the use case. On the other hand, it allows tweaking the algorithm
 with many optional arguments. Moreover, new optional parameters can be added in
 a backward-compatible way. A lot of care is taken to make the error feedback
@@ -123,15 +120,15 @@ let shortest_paths = ShortestPaths::on(&graph)
 
 ### Separation of graph storage and semantics
 
-In gryf, high-level semantics provided by user-facing types are strictly
-separated from the underlying storage/representation. The graph data can be
-stored in a common representation (e.g., adjacency list or adjacency matrix),
-but it can as well be stored in or represented by a custom, problem-tailored
-implementation, as long as it implements provided interfaces.
+High-level semantics provided by user-facing types are strictly separated from
+the underlying storage/representation. The graph data can be stored in a common
+representation (e.g., adjacency list or adjacency matrix), but it can also be
+stored in or represented by a custom, problem-tailored implementation, as long
+as it implements provided interfaces.
 
-On top of a storage, there is an encapsulation with clear semantics. The most
-general is a generic graph, but restricted forms include simple graph (without
-parallel edges), path, bipartite graph and so on. Among the advantages of
+On top of storage, there is an encapsulation with clear semantics. The most
+general is a generic graph, but restricted forms include simple graphs (without
+parallel edges), paths, bipartite graphs and so on. Among the advantages of
 restrictive encapsulations are:
 
 * The type of graph clearly communicates the intention and structure.
@@ -155,7 +152,9 @@ let mut graph = Graph::new_undirected_in(AdjMatrix::default());
 * [graphlib](https://crates.io/crates/graphlib)
 * [graphific](https://crates.io/crates/graphific)
 
-See the differences between them and gryf in [this comparison repository](https://github.com/pnevyk/rusty-graphs).
+Check the [rusty graphs](https://github.com/pnevyk/rusty-graphs) repository for
+a detailed comparison of gryf and other graph libraries available for Rust with
+examples and commentary.
 
 ## License
 

gryf-derive/LICENSE

@@ -0,0 +1 @@
+../LICENSE

gryf-derive/README.md

@@ -0,0 +1,8 @@
+# gryf-derive
+
+Derive macros for [gryf](https://github.com/pnevyk/gryf).
+
+## License
+
+Dual-licensed under [MIT](LICENSE) and [UNLICENSE](UNLICENSE). Feel free to use
+it, contribute or spread the word.

gryf-derive/UNLICENSE

@@ -0,0 +1 @@
+../UNLICENSE

gryf/LICENSE

@@ -0,0 +1 @@
+../LICENSE

gryf/README.md

@@ -0,0 +1 @@
+../README.md

gryf/UNLICENSE

@@ -0,0 +1 @@
+../UNLICENSE

gryf/docs/include/algo.on.md

@@ -0,0 +1 @@
+Initializes the algorithm to be performed on given graph.

gryf/docs/include/algo.run.md

@@ -0,0 +1 @@
+Runs the algorithm.

gryf/docs/include/algo.using.md

@@ -0,0 +1 @@
+Chooses the algorithm given in the argument.

gryf/docs/include/algo.using_opt.md

@@ -0,0 +1,2 @@
+Chooses the algorithm given in the argument or leaves it unspecified if `None`
+is passed.

gryf/docs/include/connect_vertices.connect_vertices.md

@@ -0,0 +1 @@
+Adds an edge between _(u, v)_ whenever the predicate returns `Some`.

gryf/docs/include/create.empty.md

@@ -0,0 +1 @@
+Creates a graph with zero capacities.

gryf/docs/include/create.with_capacity.md

@@ -0,0 +1 @@
+Creates a graph with given vertex and edge capacities.

gryf/docs/include/edge_set.contains_edge.md

@@ -0,0 +1 @@
+Returns `true` if the graph contains the given edge.

gryf/docs/include/edge_set.contains_edge_between.md

@@ -0,0 +1 @@
+Returns `true` if the graph contains an edge between two vertices.

gryf/docs/include/edge_set.edge_bound.md

@@ -0,0 +1,6 @@
+Returns the highest edge ID currently in use.
+
+This might be useful in algorithms that use arrays. Before using this, check
+whether [`CompactIdMap`](crate::core::id::CompactIdMap) returned by
+[`edge_id_map`](crate::core::EdgeSet::edge_id_map) doesn't satisfy your needs
+first.

gryf/docs/include/edge_set.edge_count.md

@@ -0,0 +1 @@
+Returns the number of edges in the graph.

gryf/docs/include/edge_set.edge_id.md

@@ -0,0 +1,3 @@
+Returns all edges between two vertices.
+
+Returns an empty iterator if either of the endpoints don't exist.

gryf/docs/include/edge_set.edge_id_any.md

@@ -0,0 +1 @@
+Returns an edge between two vertices, if any exist.

gryf/docs/include/edge_set.edge_id_map.md

@@ -0,0 +1,3 @@
+Returns a mapping of edge IDs to virtual IDs representing a contiguous sequence.
+
+This might be useful in algorithms that use arrays.

gryf/docs/include/edge_set.edges_by_id.md

@@ -0,0 +1 @@
+Returns all edges in the graph.

gryf/docs/include/edge_set.endpoints.md

@@ -0,0 +1 @@
+Returns the endpoints of the given edge, if it exists.

gryf/docs/include/extend_with_edges.extend_with_edges.md

@@ -0,0 +1 @@
+Adds edges in given iterator to the graph.

gryf/docs/include/extend_with_vertices.extend_with_vertices.md

@@ -0,0 +1 @@
+Adds vertices in given iterator to the graph.

gryf/docs/include/extend_with_vertices.from_vertices.md

@@ -0,0 +1 @@
+Creates a graph with vertices from given iterator.

gryf/docs/include/graph_add.add_edge.md

@@ -0,0 +1,5 @@
+Adds a new edge between two vertices.
+
+# Panics
+
+Panics if the adding operation fails.

gryf/docs/include/graph_add.add_edge_connecting.md

@@ -0,0 +1,5 @@
+Adds a new edge between two vertices, adding the vertices if necessary.
+
+# Panics
+
+Panics if the adding operation fails.

gryf/docs/include/graph_add.add_vertex.md

@@ -0,0 +1,5 @@
+Adds a new vertex to the graph.
+
+# Panics
+
+Panics if the adding operation fails.

gryf/docs/include/graph_add.get_or_add_vertex.md

@@ -0,0 +1,5 @@
+Finds and returns a vertex by its attribute or adds it if not found.
+
+# Panics
+
+Panics if the adding operation fails.

gryf/docs/include/graph_add.try_add_edge.md

@@ -0,0 +1 @@
+Adds a new edge between two vertices, returning error in case of failure.

gryf/docs/include/graph_add.try_add_edge_connecting.md

@@ -0,0 +1 @@
+Adds a new edge between two vertices, adding the vertices if necessary.

gryf/docs/include/graph_add.try_add_vertex.md

@@ -0,0 +1 @@
+Adds a new vertex to the graph, returning error in case of failure.

gryf/docs/include/graph_add.try_get_or_add_vertex.md

@@ -0,0 +1 @@
+Finds and returns a vertex by its attribute or adds it if not found.

gryf/docs/include/graph_base.edge_count_hint.md

@@ -0,0 +1 @@
+Returns the _upper bound_ of the edge count, if available.

gryf/docs/include/graph_base.is_directed.md

@@ -0,0 +1 @@
+Returns `true` if the graph is directed.

gryf/docs/include/graph_base.vertex_count_hint.md

@@ -0,0 +1 @@
+Returns the _upper bound_ of the vertex count, if available.

gryf/docs/include/graph_full.clear.md

@@ -0,0 +1 @@
+Removes all vertices and edges from the graph.

gryf/docs/include/graph_full.clear_edges.md

@@ -0,0 +1 @@
+Removes all edges from the graph.

gryf/docs/include/graph_full.remove_edge.md

@@ -0,0 +1,3 @@
+Removes an edge from the graph.
+
+Returns the edge attribute if the edge was present, or `None` otherwise.

gryf/docs/include/graph_full.remove_edge_any_between.md

@@ -0,0 +1,3 @@
+Removes an edge between two vertices, if any exist.
+
+Returns the edge attribute if an edge was present, or `None` otherwise.

gryf/docs/include/graph_full.remove_edges_between.md

@@ -0,0 +1 @@
+Removes all edges between two vertices.

gryf/docs/include/graph_full.remove_vertex.md

@@ -0,0 +1,3 @@
+Removes a vertex from the graph.
+
+Returns the vertex attribute if the vertex was present, or `None` otherwise.

gryf/docs/include/graph_mut.edge_mut.md

@@ -0,0 +1 @@
+Returns a mutable reference to the edge attribute, if it exists.

gryf/docs/include/graph_mut.replace_edge.md

@@ -0,0 +1,5 @@
+Replaces the attribute of an edge with a new value, returning the old one.
+
+# Panics
+
+Panics if the edge does not exist.

gryf/docs/include/graph_mut.replace_vertex.md

@@ -0,0 +1,5 @@
+Replaces the attribute of a vertex with a new value, returning the old one.
+
+# Panics
+
+Panics if the vertex does not exist.

gryf/docs/include/graph_mut.try_replace_edge.md

@@ -0,0 +1,3 @@
+Replaces the attribute of an edge with a new value, returning the old one.
+
+If the edge does not exist, an error is returned.

gryf/docs/include/graph_mut.try_replace_vertex.md

@@ -0,0 +1,3 @@
+Replaces the attribute of a vertex with a new value, returning the old one.
+
+If the vertex does not exist, an error is returned.

gryf/docs/include/graph_mut.vertex_mut.md

@@ -0,0 +1 @@
+Returns a mutable reference to the vertex attribute, if it exists.

gryf/docs/include/graph_ref.edge.md

@@ -0,0 +1 @@
+Returns a reference to the edge attribute, if it exists.

gryf/docs/include/graph_ref.edges.md

@@ -0,0 +1 @@
+Returns all edges in the graph with their attributes and endpoints.

gryf/docs/include/graph_ref.find_vertex.md

@@ -0,0 +1 @@
+Finds a vertex by its attribute.

gryf/docs/include/graph_ref.vertex.md

@@ -0,0 +1 @@
+Returns a reference to the vertex attribute, if it exists.

gryf/docs/include/graph_ref.vertices.md

@@ -0,0 +1 @@
+Returns all vertices in the graph with their attributes.

gryf/docs/include/graph_weak.edge_weak.md

@@ -0,0 +1 @@
+Returns a reference to the edge attribute, if it exists.

gryf/docs/include/graph_weak.vertex_weak.md

@@ -0,0 +1 @@
+Returns a reference to the vertex attribute, if it exists.

gryf/docs/include/neighbors.degree_directed.md

@@ -0,0 +1,9 @@
+Returns the out or in degree of the given vertex, depending on the edge
+direction argument.
+
+In undirected graphs the direction is ignored and the returned value is the same
+as from [degree_undirected](Self::degree_undirected).
+
+# Panics
+
+Panics if the vertex does not exist.

gryf/docs/include/neighbors.degree_undirected.md

@@ -0,0 +1,5 @@
+Returns the total degree of the given vertex.
+
+# Panics
+
+Panics if the vertex does not exist.

gryf/docs/include/neighbors.neighbors_directed.md

@@ -0,0 +1,8 @@
+Returns all neighbors of the given vertex in the given direction.
+
+In undirected graphs the edge direction is ignored and the returned items are
+the same as from [neighbors_undirected](Self::neighbors_undirected).
+
+# Panics
+
+Panics if the vertex does not exist.

gryf/docs/include/neighbors.neighbors_undirected.md

@@ -0,0 +1,7 @@
+Returns all neighbors of the given vertex, regardless of edge direction.
+
+In directed graphs, this means outgoing as well as incoming edges.
+
+# Panics
+
+Panics if the vertex does not exist.

gryf/docs/include/vertex_set.contains_vertex.md

@@ -0,0 +1 @@
+Returns `true` if the graph contains the given vertex.

gryf/docs/include/vertex_set.vertex_bound.md

@@ -0,0 +1,6 @@
+Returns the highest vertex ID currently in use.
+
+This might be useful in algorithms that use arrays. Before using this, check
+whether [`CompactIdMap`](crate::core::id::CompactIdMap) returned by
+[`vertex_id_map`](crate::core::VertexSet::vertex_id_map) doesn't satisfy your
+needs first.

gryf/docs/include/vertex_set.vertex_count.md

@@ -0,0 +1 @@
+Returns the number of vertices in the graph.

gryf/docs/include/vertex_set.vertex_id_map.md

@@ -0,0 +1,4 @@
+Returns a mapping of vertex IDs to virtual IDs representing a contiguous
+sequence.
+
+This might be useful in algorithms that use arrays.

gryf/docs/include/vertex_set.vertices_by_id.md

@@ -0,0 +1 @@
+Returns all vertices in the graph.

gryf/docs/include/visit.new.md

@@ -0,0 +1 @@
+Initializes the traversal state from the given graph.

gryf/docs/include/visit.reset.md

@@ -0,0 +1 @@
+Resets the traversal state.

gryf/docs/include/visit.start.md

@@ -0,0 +1 @@
+Starts the traversal traversal from a single root.

gryf/docs/include/visit.start_all.md

@@ -0,0 +1 @@
+Performs the traversal traversal from all vertices of the graph.

gryf/docs/include/visit.start_multi.md

@@ -0,0 +1 @@
+Performs the traversal traversal from given vertices in the graph.

gryf/docs/include/visit.visited.md

@@ -0,0 +1 @@
+Returns the set of vertices visited so far.