docs: Clarify when graph methods return None? (#491)
This is a docs change, and should not affect any functionality.
While looking about the API, I didn't quite understand why I had to `unwrap()` every time I wanted to access an edge or a node. I understand now it's because that weight or node might not exist, but that was only clear to me after looking at the source code.
This change adds a line to the relevant docstrings that explain when a `Some()` will be returned vs when a `None` will be returned.
The docstring for `remove_node` already had a similar line in it:
```
/// Remove `a` from the graph if it exists, and return its weight.
/// If it doesn't exist in the graph, return `None`.
```
So I made sure the lines I added were phrased similarly to keep the code base consistent, like
```
/// If ____ doesn't exist in the graph, return `None`.
```
diff --git a/src/graph_impl/mod.rs b/src/graph_impl/mod.rs
index c8f12a6..d0be473 100644
--- a/src/graph_impl/mod.rs
+++ b/src/graph_impl/mod.rs
@@ -534,6 +534,7 @@
/// Access the weight for node `a`.
///
+ /// If node `a` doesn't exist in the graph, return `None`.
/// Also available with indexing syntax: `&graph[a]`.
pub fn node_weight(&self, a: NodeIndex<Ix>) -> Option<&N> {
self.nodes.get(a.index()).map(|n| &n.weight)
@@ -541,6 +542,7 @@
/// Access the weight for node `a`, mutably.
///
+ /// If node `a` doesn't exist in the graph, return `None`.
/// Also available with indexing syntax: `&mut graph[a]`.
pub fn node_weight_mut(&mut self, a: NodeIndex<Ix>) -> Option<&mut N> {
self.nodes.get_mut(a.index()).map(|n| &mut n.weight)
@@ -606,6 +608,7 @@
/// Access the weight for edge `e`.
///
+ /// If edge `e` doesn't exist in the graph, return `None`.
/// Also available with indexing syntax: `&graph[e]`.
pub fn edge_weight(&self, e: EdgeIndex<Ix>) -> Option<&E> {
self.edges.get(e.index()).map(|ed| &ed.weight)
@@ -613,12 +616,15 @@
/// Access the weight for edge `e`, mutably.
///
+ /// If edge `e` doesn't exist in the graph, return `None`.
/// Also available with indexing syntax: `&mut graph[e]`.
pub fn edge_weight_mut(&mut self, e: EdgeIndex<Ix>) -> Option<&mut E> {
self.edges.get_mut(e.index()).map(|ed| &mut ed.weight)
}
/// Access the source and target nodes for `e`.
+ ///
+ /// If edge `e` doesn't exist in the graph, return `None`.
pub fn edge_endpoints(&self, e: EdgeIndex<Ix>) -> Option<(NodeIndex<Ix>, NodeIndex<Ix>)> {
self.edges
.get(e.index())
