DOC: Update docstrings for public functions in threshold module (#4167)

* DOC: Add docstring to is_threshold_graph.

* DOC: Add another example to is_threshold_graph

* DOC: Add docstring for find_threshold_graph

* STY: rm trailing whitespace

* DOC: Add imports to docstring examples

1 files changed, 51 insertions, 2 deletions

diff --git a/networkx/algorithms/threshold.py b/networkx/algorithms/threshold.py
index 1d0a34c3..f2015ae7 100644
--- a/networkx/algorithms/threshold.py
+++ b/networkx/algorithms/threshold.py
@@ -10,7 +10,31 @@ __all__ = ["is_threshold_graph", "find_threshold_graph"]
 
 def is_threshold_graph(G):
     """
-    Returns True if G is a threshold graph.
+    Returns `True` if `G` is a threshold graph.
+
+    Parameters
+    ----------
+    G : NetworkX graph instance
+        An instance of `Graph`, `DiGraph`, `MultiGraph` or `MultiDiGraph`
+
+    Returns
+    -------
+    bool
+        `True` if `G` is a threshold graph, `False` otherwise.
+
+    Examples
+    --------
+    >>> from networkx.algorithms.threshold import is_threshold_graph
+    >>> G = nx.path_graph(3)
+    >>> is_threshold_graph(G)
+    True
+    >>> G = nx.barbell_graph(3, 3)
+    >>> is_threshold_graph(G)
+    False
+
+    References
+    ----------
+    .. [1] Threshold graphs: https://en.wikipedia.org/wiki/Threshold_graph
     """
     return is_threshold_sequence(list(d for n, d in G.degree()))
 
@@ -343,9 +367,34 @@ def find_alternating_4_cycle(G):
 
 def find_threshold_graph(G, create_using=None):
     """
-    Return a threshold subgraph that is close to largest in G.
+    Returns a threshold subgraph that is close to largest in `G`.
+
     The threshold graph will contain the largest degree node in G.
 
+    Parameters
+    ----------
+    G : NetworkX graph instance
+        An instance of `Graph`, or `MultiDiGraph`
+    create_using : NetworkX graph class or `None` (default), optional
+        Type of graph to use when constructing the threshold graph.
+        If `None`, infer the appropriate graph type from the input.
+
+    Returns
+    -------
+    graph :
+        A graph instance representing the threshold graph
+
+    Examples
+    --------
+    >>> from networkx.algorithms.threshold import find_threshold_graph
+    >>> G = nx.barbell_graph(3, 3)
+    >>> T = find_threshold_graph(G)
+    >>> T.nodes # may vary
+    NodeView((7, 8, 5, 6))
+
+    References
+    ----------
+    .. [1] Threshold graphs: https://en.wikipedia.org/wiki/Threshold_graph
     """
     return threshold_graph(find_creation_sequence(G), create_using)