Fix docstrings and remove unused variables (#4501)

Co-authored-by: Dan Schult <dschult@colgate.edu>
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

19 files changed, 62 insertions, 22 deletions

diff --git a/networkx/algorithms/approximation/kcomponents.py b/networkx/algorithms/approximation/kcomponents.py
index 6fbba35c..328d6016 100644
--- a/networkx/algorithms/approximation/kcomponents.py
+++ b/networkx/algorithms/approximation/kcomponents.py
@@ -110,7 +110,6 @@ def k_components(G, min_density=0.95):
     k_core = nx.k_core
     core_number = nx.core_number
     biconnected_components = nx.biconnected_components
-    density = nx.density
     combinations = itertools.combinations
     # Exact solution for k = {1,2}
     # There is a linear time algorithm for triconnectivity, if we had an
diff --git a/networkx/algorithms/bipartite/basic.py b/networkx/algorithms/bipartite/basic.py
index 7dbbda71..66a253d4 100644
--- a/networkx/algorithms/bipartite/basic.py
+++ b/networkx/algorithms/bipartite/basic.py
@@ -210,7 +210,7 @@ def density(B, nodes):
 
     Parameters
     ----------
-    G : NetworkX graph
+    B : NetworkX graph
 
     nodes: list or container
       Nodes in one node set of the bipartite graph.
@@ -262,7 +262,7 @@ def degrees(B, nodes, weight=None):
 
     Parameters
     ----------
-    G : NetworkX graph
+    B : NetworkX graph
 
     nodes: list or container
       Nodes in one node set of the bipartite graph.
diff --git a/networkx/algorithms/chordal.py b/networkx/algorithms/chordal.py
index aa89ca5b..0c7e3014 100644
--- a/networkx/algorithms/chordal.py
+++ b/networkx/algorithms/chordal.py
@@ -103,7 +103,7 @@ def find_induced_nodes(G, s, t, treewidth_bound=sys.maxsize):
         Source node to look for induced nodes
     t : node
         Destination node to look for induced nodes
-    treewith_bound: float
+    treewidth_bound: float
         Maximum treewidth acceptable for the graph H. The search
         for induced nodes will end as soon as the treewidth_bound is exceeded.
 
diff --git a/networkx/algorithms/regular.py b/networkx/algorithms/regular.py
index 5b302e2a..c51c48fe 100644
--- a/networkx/algorithms/regular.py
+++ b/networkx/algorithms/regular.py
@@ -68,7 +68,7 @@ def k_factor(G, k, matching_weight="weight"):
     G : NetworkX graph
       Undirected graph
 
-    weight: string, optional (default='weight')
+    matching_weight: string, optional (default='weight')
        Edge data key corresponding to the edge weight.
        Used for finding the max-weighted perfect matching.
        If key not found, uses 1 as weight.
diff --git a/networkx/algorithms/shortest_paths/astar.py b/networkx/algorithms/shortest_paths/astar.py
index 7833044b..d067381f 100644
--- a/networkx/algorithms/shortest_paths/astar.py
+++ b/networkx/algorithms/shortest_paths/astar.py
@@ -157,6 +157,17 @@ def astar_path_length(G, source, target, heuristic=None, weight="weight"):
        from the a node to the target.  The function takes
        two nodes arguments and must return a number.
 
+    weight : string or function
+       If this is a string, then edge weights will be accessed via the
+       edge attribute with this key (that is, the weight of the edge
+       joining `u` to `v` will be ``G.edges[u, v][weight]``). If no
+       such edge attribute exists, the weight of the edge is assumed to
+       be one.
+       If this is a function, the weight of an edge is the value
+       returned by the function. The function must accept exactly three
+       positional arguments: the two endpoints of an edge and the
+       dictionary of edge attributes for that edge. The function must
+       return a number.
     Raises
     ------
     NetworkXNoPath
diff --git a/networkx/algorithms/shortest_paths/weighted.py b/networkx/algorithms/shortest_paths/weighted.py
index 84149f09..dedc691b 100644
--- a/networkx/algorithms/shortest_paths/weighted.py
+++ b/networkx/algorithms/shortest_paths/weighted.py
@@ -1115,6 +1115,9 @@ def bellman_ford_predecessor_and_distance(
     source: node label
        Starting node for path
 
+    target : node label, optional
+       Ending node for path
+
     weight : string or function
        If this is a string, then edge weights will be accessed via the
        edge attribute with this key (that is, the weight of the edge
@@ -1558,6 +1561,19 @@ def single_source_bellman_ford(G, source, target=None, weight="weight"):
     target : node label, optional
        Ending node for path
 
+    weight : string or function
+       If this is a string, then edge weights will be accessed via the
+       edge attribute with this key (that is, the weight of the edge
+       joining `u` to `v` will be ``G.edges[u, v][weight]``). If no
+       such edge attribute exists, the weight of the edge is assumed to
+       be one.
+
+       If this is a function, the weight of an edge is the value
+       returned by the function. The function must accept exactly three
+       positional arguments: the two endpoints of an edge and the
+       dictionary of edge attributes for that edge. The function must
+       return a number.
+
     Returns
     -------
     distance, path : pair of dictionaries, or numeric and list
diff --git a/networkx/algorithms/simple_paths.py b/networkx/algorithms/simple_paths.py
index 25173227..b762f820 100644
--- a/networkx/algorithms/simple_paths.py
+++ b/networkx/algorithms/simple_paths.py
@@ -24,6 +24,8 @@ def is_simple_path(G, nodes):
 
     Parameters
     ----------
+    G : graph
+        A NetworkX graph.
     nodes : list
         A list of one or more nodes in the graph `G`.
 
diff --git a/networkx/algorithms/smallworld.py b/networkx/algorithms/smallworld.py
index eb164177..eb2b6401 100644
--- a/networkx/algorithms/smallworld.py
+++ b/networkx/algorithms/smallworld.py
@@ -90,8 +90,6 @@ def random_reference(G, niter=1, connectivity=True, seed=None):
             # choose target uniformly from neighbors
             b = seed.choice(list(G.neighbors(a)))
             d = seed.choice(list(G.neighbors(c)))
-            bi = keys.index(b)
-            di = keys.index(d)
             if b in [a, c, d] or d in [a, b, c]:
                 continue  # all vertices should be different
 
diff --git a/networkx/classes/digraph.py b/networkx/classes/digraph.py
index 6e2de3f6..04cd6b5c 100644
--- a/networkx/classes/digraph.py
+++ b/networkx/classes/digraph.py
@@ -570,7 +570,7 @@ class DiGraph(Graph):
 
         Parameters
         ----------
-        u, v : nodes
+        u_of_edge, v_of_edge : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         attr : keyword arguments, optional
diff --git a/networkx/classes/function.py b/networkx/classes/function.py
index b789776b..1d2f2866 100644
--- a/networkx/classes/function.py
+++ b/networkx/classes/function.py
@@ -1123,6 +1123,8 @@ def selfloop_edges(G, data=False, keys=False, default=None):
 
     Parameters
     ----------
+    G : graph
+        A NetworkX graph.
     data : string or bool, optional (default=False)
         Return selfloop edges as two tuples (u, v) (data=False)
         or three-tuples (u, v, datadict) (data=True)
diff --git a/networkx/classes/graph.py b/networkx/classes/graph.py
index 8ad9a32e..4ba639f4 100644
--- a/networkx/classes/graph.py
+++ b/networkx/classes/graph.py
@@ -831,7 +831,7 @@ class Graph:
 
         Parameters
         ----------
-        u, v : nodes
+        u_of_edge, v_of_edge : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         attr : keyword arguments, optional
diff --git a/networkx/generators/random_graphs.py b/networkx/generators/random_graphs.py
index 3dd35924..5e1a2f06 100644
--- a/networkx/generators/random_graphs.py
+++ b/networkx/generators/random_graphs.py
@@ -1226,7 +1226,7 @@ def random_kernel_graph(n, kernel_integral, kernel_root=None, seed=None):
     ----------
     n : int
         The number of nodes
-    kernal_integral : function
+    kernel_integral : function
         Function that returns the definite integral of the kernel $\kappa(x,y)$,
         $F(y,a,b) := \int_a^b \kappa(x,y)dx$
     kernel_root: function (optional)
diff --git a/networkx/generators/trees.py b/networkx/generators/trees.py
index 7153a2ed..85e89220 100644
--- a/networkx/generators/trees.py
+++ b/networkx/generators/trees.py
@@ -163,6 +163,8 @@ def random_tree(n, seed=None, create_using=None):
     seed : integer, random_state, or None (default)
         Indicator of random number generation state.
         See :ref:`Randomness<randomness>`.
+    create_using : NetworkX graph constructor, optional (default=nx.Graph)
+        Graph type to create. If graph instance, then cleared before populated.
 
     Returns
     -------
diff --git a/networkx/readwrite/gexf.py b/networkx/readwrite/gexf.py
index 4168a7d2..3560370b 100644
--- a/networkx/readwrite/gexf.py
+++ b/networkx/readwrite/gexf.py
@@ -50,6 +50,8 @@ def write_gexf(G, path, encoding="utf-8", prettyprint=True, version="1.2draft"):
        Encoding for text data.
     prettyprint : bool (optional, default: True)
        If True use line breaks and indenting in output XML.
+    version: string (optional, default: '1.2draft')
+       The version of GEXF to be used for nodes attributes checking
 
     Examples
     --------
diff --git a/networkx/readwrite/json_graph/adjacency.py b/networkx/readwrite/json_graph/adjacency.py
index cf7c8c72..4b869e4f 100644
--- a/networkx/readwrite/json_graph/adjacency.py
+++ b/networkx/readwrite/json_graph/adjacency.py
@@ -90,11 +90,6 @@ def adjacency_graph(data, directed=False, multigraph=True, attrs=_attrs):
     data : dict
         Adjacency list formatted graph data
 
-    Returns
-    -------
-    G : NetworkX graph
-       A NetworkX graph object
-
     directed : bool
         If True, and direction not specified in data, return a directed graph.
 
@@ -107,6 +102,11 @@ def adjacency_graph(data, directed=False, multigraph=True, attrs=_attrs):
         data. The values should be unique. Default value:
         :samp:`dict(id='id', key='key')`.
 
+    Returns
+    -------
+    G : NetworkX graph
+       A NetworkX graph object
+
     Examples
     --------
     >>> from networkx.readwrite import json_graph
diff --git a/networkx/readwrite/json_graph/tree.py b/networkx/readwrite/json_graph/tree.py
index bb16f323..2863712d 100644
--- a/networkx/readwrite/json_graph/tree.py
+++ b/networkx/readwrite/json_graph/tree.py
@@ -96,17 +96,16 @@ def tree_graph(data, attrs=_attrs):
     ----------
     data : dict
         Tree formatted graph data
-
-    Returns
-    -------
-    G : NetworkX DiGraph
-
     attrs : dict
         A dictionary that contains two keys 'id' and 'children'. The
         corresponding values provide the attribute names for storing
         NetworkX-internal graph data. The values should be unique. Default
         value: :samp:`dict(id='id', children='children')`.
 
+    Returns
+    -------
+    G : NetworkX DiGraph
+
     Examples
     --------
     >>> from networkx.readwrite import json_graph
diff --git a/networkx/readwrite/multiline_adjlist.py b/networkx/readwrite/multiline_adjlist.py
index 0dd19fed..17d72f4a 100644
--- a/networkx/readwrite/multiline_adjlist.py
+++ b/networkx/readwrite/multiline_adjlist.py
@@ -141,6 +141,10 @@ def write_multiline_adjlist(G, path, delimiter=" ", comments="#", encoding="utf-
     ----------
     G : NetworkX graph
 
+    path : string or file
+       Filename or file handle to write to.
+       Filenames ending in .gz or .bz2 will be compressed.
+
     comments : string, optional
        Marker for comment lines
 
@@ -203,6 +207,9 @@ def parse_multiline_adjlist(
     nodetype : Python type, optional
        Convert nodes to this type.
 
+    edgetype : Python type, optional
+       Convert edges to this type.
+
     comments : string, optional
        Marker for comment lines
 
diff --git a/networkx/readwrite/nx_shp.py b/networkx/readwrite/nx_shp.py
index 0c1a6507..1bfc031d 100644
--- a/networkx/readwrite/nx_shp.py
+++ b/networkx/readwrite/nx_shp.py
@@ -205,6 +205,8 @@ def write_shp(G, outdir):
 
     Parameters
     ----------
+    G : NetworkX graph
+        Directed graph
     outdir : directory path
        Output directory for the two shapefiles.
 
diff --git a/networkx/readwrite/nx_yaml.py b/networkx/readwrite/nx_yaml.py
index 294922ea..80bd5dfd 100644
--- a/networkx/readwrite/nx_yaml.py
+++ b/networkx/readwrite/nx_yaml.py
@@ -29,9 +29,9 @@ def write_yaml(G_to_be_yaml, path_for_yaml_output, **kwds):
 
     Parameters
     ----------
-    G : graph
+    G_to_be_yaml : graph
        A NetworkX graph
-    path : file or string
+    path_for_yaml_output : file or string
        File or filename to write.
        Filenames ending in .gz or .bz2 will be compressed.