Improves description bfs_predecessors and bfs_successors. (#4438)

* Improves description bfs_predecessors and bfs_successors.

Corrects the return type of bfs_predecessors.
Adds more details to the return type of bfs_successors.

Adds doctests for bfs_predecessors and bfs_successors that
are indicative for the behaviour of these functions on DiGraphs.
Previous tests only used these functions on undirect Graphs.

* Update networkx/algorithms/traversal/breadth_first_search.py

Co-authored-by: Dan Schult <dschult@colgate.edu>

* Update networkx/algorithms/traversal/breadth_first_search.py

Co-authored-by: Dan Schult <dschult@colgate.edu>

* Removes additional space

Co-authored-by: Dan Schult <dschult@colgate.edu>

1 files changed, 14 insertions, 6 deletions

diff --git a/networkx/algorithms/traversal/breadth_first_search.py b/networkx/algorithms/traversal/breadth_first_search.py
index 3432ddcd..859898c6 100644
--- a/networkx/algorithms/traversal/breadth_first_search.py
+++ b/networkx/algorithms/traversal/breadth_first_search.py
@@ -250,8 +250,8 @@ def bfs_predecessors(G, source, depth_limit=None, sort_neighbors=None):
     Returns
     -------
     pred: iterator
-        (node, predecessors) iterator where predecessors is the list of
-        predecessors of the node.
+        (node, predecessor) iterator where `predecessor` is the predecessor of
+        `node` in a breadth first search starting from `source`.
 
     Examples
     --------
@@ -267,7 +267,11 @@ def bfs_predecessors(G, source, depth_limit=None, sort_neighbors=None):
     >>> nx.add_path(M, [2, 7, 8, 9, 10])
     >>> print(sorted(nx.bfs_predecessors(M, source=1, depth_limit=3)))
     [(0, 1), (2, 1), (3, 2), (4, 3), (7, 2), (8, 7)]
-
+    >>> N = nx.DiGraph()
+    >>> nx.add_path(N, [0, 1, 2, 3, 4, 7])
+    >>> nx.add_path(N, [3, 5, 6, 7])
+    >>> print(sorted(nx.bfs_predecessors(N, source=2)))
+    [(3, 2), (4, 3), (5, 3), (6, 5), (7, 4)]
 
     Notes
     -----
@@ -310,8 +314,9 @@ def bfs_successors(G, source, depth_limit=None, sort_neighbors=None):
     Returns
     -------
     succ: iterator
-       (node, successors) iterator where successors is the list of
-       successors of the node.
+       (node, successors) iterator where `successors` is the non-empty list of
+       successors of `node` in a breadth first search from `source`.
+       To appear in the iterator, `node` must have successors.
 
     Examples
     --------
@@ -327,7 +332,10 @@ def bfs_successors(G, source, depth_limit=None, sort_neighbors=None):
     >>> nx.add_path(G, [2, 7, 8, 9, 10])
     >>> print(dict(nx.bfs_successors(G, source=1, depth_limit=3)))
     {1: [0, 2], 2: [3, 7], 3: [4], 7: [8]}
-
+    >>> G = nx.DiGraph()
+    >>> nx.add_path(G, [0, 1, 2, 3, 4, 5])
+    >>> print(dict(nx.bfs_successors(G, source=3)))
+    {3: [4], 4: [5]}
 
     Notes
     -----