Docs and consistency cleanup for rustworkx-core generators

rustworkx-core/src/generators/barbell_graph.rs

@@ -19,33 +19,32 @@ use super::utils::get_num_nodes;
 use super::utils::pairwise;
 use super::InvalidInputError;
 
-/// Generate an undirected barbell graph where two identical mesh graphs are
+/// Generate an undirected barbell graph where two identical complete graphs are
 /// connected by a path.
 ///
 /// .. note::
 ///
-///   If neither `num_path_nodes` nor `path_weights` (described below) is not specified
-///   then this is equivalent to two mesh graphs joined together.
+///   If neither `num_path_nodes` nor `path_weights` (described below) are
+///   specified, then this is equivalent to two complete graphs joined together.
 ///
 /// Arguments:
 ///
 /// * `num_mesh_nodes` - The number of nodes to generate the mesh graph
 ///     with. Node weights will be None if this is specified. If both
-///     `num_mesh_nodes` and `mesh_weights` are set this will be ignored and
+///     `num_mesh_nodes` and `mesh_weights` are set, this will be ignored and
 ///     `mesh_weights` will be used.
 /// * `num_path_nodes` - The number of nodes to generate the path
 ///     with. Node weights will be None if this is specified. If both
-///     `num_path_nodes` and `path_weights` are set this will be ignored and
+///     `num_path_nodes` and `path_weights` are set, this will be ignored and
 ///     `path_weights` will be used.
 /// * `mesh_weights` - A list of node weights for the mesh graph. If both
-///     `num_mesh_nodes` and `mesh_weights` are set `num_mesh_nodes` will
+///     `num_mesh_nodes` and `mesh_weights` are set, `num_mesh_nodes` will
 ///     be ignored and `mesh_weights` will be used.
 /// * `path_weights` - A list of node weights for the path. If both
-///     `num_path_nodes` and `path_weights` are set `num_path_nodes` will
+///     `num_path_nodes` and `path_weights` are set, `num_path_nodes` will
 ///     be ignored and `path_weights` will be used.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if weights are specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if node weights are specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
 ///
@@ -147,7 +146,7 @@ where
         }
     };
     let pathlen = path_nodes.len();
-    if pathlen > 0 {
+    if !path_nodes.is_empty() {
         graph.add_edge(
             graph.from_index(meshlen - 1),
             graph.from_index(meshlen),

rustworkx-core/src/generators/binomial_tree_graph.rs

@@ -21,15 +21,14 @@ use super::InvalidInputError;
 ///
 /// * `order` - The order of the binomial tree.
 /// * `weights` - A `Vec` of node weight objects. If the number of weights is
-///     less than 2**order extra nodes with None will be appended.
+///     less than 2**order, extra nodes with None will be appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust
@@ -104,22 +103,6 @@ where
             None => graph.add_node(default_node_weight()),
         };
     }
-
-    fn find_edge<G>(graph: &mut G, source: usize, target: usize) -> bool
-    where
-        G: NodeIndexable,
-        for<'b> &'b G: GraphBase<NodeId = G::NodeId> + IntoEdgeReferences,
-    {
-        let mut found = false;
-        for edge in graph.edge_references() {
-            if graph.to_index(edge.source()) == source && graph.to_index(edge.target()) == target {
-                found = true;
-                break;
-            }
-        }
-        found
-    }
-
     let mut n = 1;
     let zero_index = 0;
     for _ in 0..order {
@@ -132,30 +115,26 @@ where
             let source_index = source + n;
             let target_index = target + n;
 
-            if !find_edge(&mut graph, source_index, target_index) {
-                graph.add_edge(
-                    graph.from_index(source_index),
-                    graph.from_index(target_index),
-                    default_edge_weight(),
-                );
-            }
-            if bidirectional && !find_edge(&mut graph, target_index, source_index) {
-                graph.add_edge(
+            graph.update_edge(
+                graph.from_index(source_index),
+                graph.from_index(target_index),
+                default_edge_weight(),
+            );
+            if bidirectional {
+                graph.update_edge(
                     graph.from_index(target_index),
                     graph.from_index(source_index),
                     default_edge_weight(),
                 );
             }
         }
-        if !find_edge(&mut graph, zero_index, n) {
-            graph.add_edge(
-                graph.from_index(zero_index),
-                graph.from_index(n),
-                default_edge_weight(),
-            );
-        }
-        if bidirectional && !find_edge(&mut graph, n, zero_index) {
-            graph.add_edge(
+        graph.update_edge(
+            graph.from_index(zero_index),
+            graph.from_index(n),
+            default_edge_weight(),
+        );
+        if bidirectional {
+            graph.update_edge(
                 graph.from_index(n),
                 graph.from_index(zero_index),
                 default_edge_weight(),

rustworkx-core/src/generators/complete_graph.rs

@@ -21,12 +21,11 @@ use super::InvalidInputError;
 /// Arguments:
 ///
 /// * `num_nodes` - The number of nodes to create a complete graph for. Either this or
-///     `weights must be specified. If both this and `weights are specified, weights
+///     `weights` must be specified. If both this and `weights` are specified, `weights`
 ///     will take priorty and this argument will be ignored
 /// * `weights` - A `Vec` of node weight objects.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
 ///

rustworkx-core/src/generators/cycle_graph.rs

@@ -21,17 +21,16 @@ use super::InvalidInputError;
 /// Arguments:
 ///
 /// * `num_nodes` - The number of nodes to create a cycle graph for. Either this or
-///     `weights must be specified. If both this and `weights are specified, weights
+///     `weights` must be specified. If both this and `weights` are specified, `weights`
 ///     will take priorty and this argument will be ignored.
 /// * `weights` - A `Vec` of node weight objects.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/full_rary_tree_graph.rs

@@ -21,18 +21,19 @@ use super::InvalidInputError;
 /// Creates a full r-ary tree of `n` nodes.
 /// Sometimes called a k-ary, n-ary, or m-ary tree.
 ///
+/// Arguments:
+///
 /// * `branching factor` - The number of children at each node.
 /// * `num_nodes` - The number of nodes in the graph.
 /// * `weights` - A list of node weights. If the number of weights is
-///     less than n, extra nodes with with None weight will be appended.
+///     less than n, extra nodes with None weight will be appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/grid_graph.rs

@@ -21,7 +21,7 @@ use super::InvalidInputError;
 ///
 /// * `rows` - The number of rows to generate the graph with.
 ///     If specified, cols also need to be specified.
-/// * `cols`: The number of rows to generate the graph with.
+/// * `cols`: The number of columns to generate the graph with.
 ///     If specified, rows also need to be specified. rows*cols
 ///     defines the number of nodes in the graph.
 /// * `weights`: A `Vec` of node weights. Nodes are filled row wise.
@@ -32,11 +32,10 @@ use super::InvalidInputError;
 ///     If number of nodes(rows*cols) is greater than length of
 ///     weights list, extra nodes with None weight are appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
 ///     If the graph is undirected this will result in a parallel edge.
 ///

rustworkx-core/src/generators/heavy_hex_graph.rs

@@ -54,16 +54,17 @@ use super::InvalidInputError;
 ///     ... D   D-S-D ...
 ///
 ///
-/// * `d` - Distance of the code. If ``d`` is set to ``1`` a graph with a
-///     single node will be returned. d must be an odd number.
+/// Arguments:
+///
+/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
+///     single node will be returned. `d` must be an odd number.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/heavy_square_graph.rs

@@ -43,12 +43,17 @@ use super::InvalidInputError;
 /// This function implements Fig 10.b left of the `paper <https://arxiv.org/abs/1907.09528>`_.
 /// This function doesn't support the variant Fig 10.b right.
 ///
-/// :param int d: distance of the code. If ``d`` is set to ``1`` a
-///     :class:`~rustworkx.PyDiGraph` with a single node will be returned.
-/// :param bool multigraph: When set to False the output
-///     :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and
-///     won't  allow parallel edges to be added. Instead
-///     calls which would create a parallel edge will update the existing edge.
+/// Arguments:
+///
+/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
+///     single node will be returned. `d` must be an odd number.
+/// * `default_node_weight` - A callable that will return the weight to use
+///     for newly created nodes. This is ignored if `weights` is specified.
+/// * `default_edge_weight` - A callable that will return the weight object
+///     to use for newly created edges.
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
+///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/hexagonal_lattice_graph.rs

@@ -24,13 +24,12 @@ use super::InvalidInputError;
 /// * `rows` - The number of rows to generate the graph with.
 /// * `cols` - The number of columns to generate the graph with.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/lollipop_graph.rs

@@ -15,19 +15,18 @@ use std::hash::Hash;
 use petgraph::data::{Build, Create};
 use petgraph::visit::{Data, GraphProp, NodeIndexable};
 
-use super::utils::pairwise;
+use super::utils::{get_num_nodes, pairwise};
 use super::InvalidInputError;
 
-/// Generate a lollipop graph
+/// Generate an undirected lollipop graph where a complete graph is connected to a
+/// path.
 ///
-/// Arguments:
+/// .. note::
 ///
-/// Generate an undirected lollipop graph where a mesh graph is connected to a
-/// path.
+///   If neither `num_path_nodes` nor `path_weights` (described below) are
+///   specified, then this is equivalent to a complete graph.
 ///
-/// If neither `num_path_nodes` nor `path_weights` (both described
-/// below) are specified then this is equivalent to
-/// :func:`~rustworkx.generators.mesh_graph`
+/// Arguments:
 ///
 /// * `num_mesh_nodes` - The number of nodes to generate the mesh graph
 ///     with. Node weights will be None if this is specified. If both
@@ -44,8 +43,7 @@ use super::InvalidInputError;
 ///     `num_path_nodes` and `path_weights` are set `num_path_nodes` will
 ///     be ignored and `path_weights` will be used.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
 ///
@@ -98,12 +96,7 @@ where
     if num_mesh_nodes.is_none() && mesh_weights.is_none() {
         return Err(InvalidInputError {});
     }
-    let num_nodes: usize;
-    if let Some(mesh_nodes) = num_mesh_nodes {
-        num_nodes = mesh_nodes;
-    } else {
-        num_nodes = mesh_weights.as_ref().unwrap().len();
-    }
+    let num_nodes = get_num_nodes(&num_mesh_nodes, &mesh_weights);
     let num_edges = (num_nodes * (num_nodes - 1)) / 2;
     let mut graph = G::with_capacity(num_nodes, num_edges);
 
@@ -138,8 +131,7 @@ where
             }
         }
     };
-    let pathlen = path_nodes.len();
-    if pathlen > 0 {
+    if !path_nodes.is_empty() {
         graph.add_edge(
             graph.from_index(meshlen - 1),
             graph.from_index(meshlen),
@@ -160,6 +152,7 @@ mod tests {
     use crate::generators::lollipop_graph;
     use crate::generators::InvalidInputError;
     use crate::petgraph::visit::EdgeRef;
+
     #[test]
     fn test_lollipop_mesh_path() {
         let expected_edge_list = vec![

rustworkx-core/src/generators/mod.rs

@@ -26,7 +26,7 @@ mod path_graph;
 mod petersen_graph;
 mod star_graph;
 
-mod utils;
+pub mod utils;
 
 use std::{error::Error, fmt};
 

rustworkx-core/src/generators/path_graph.rs

@@ -21,17 +21,16 @@ use super::InvalidInputError;
 /// Arguments:
 ///
 /// * `num_nodes` - The number of nodes to create a path graph for. Either this or
-///     `weights must be specified. If both this and `weights are specified, weights
+///     `weights` must be specified. If both this and `weights` are specified, `weights`
 ///     will take priorty and this argument will be ignored
 /// * `weights` - A `Vec` of node weight objects.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust