docstring updates for `union`, `disjoint_union`, and `compose` (#5892)

* docstring updates

-  union
- disjoint_union
- compose

* fix broken link to Graph.update()

1 files changed, 53 insertions, 22 deletions

diff --git a/networkx/algorithms/operators/binary.py b/networkx/algorithms/operators/binary.py
index fcd5933e..7ea3d77a 100644
--- a/networkx/algorithms/operators/binary.py
+++ b/networkx/algorithms/operators/binary.py
@@ -15,14 +15,16 @@ __all__ = [
 
 
 def union(G, H, rename=(None, None), name=None):
-    """Return the union of graphs G and H.
+    """Combine graphs G and H. The names of nodes must be unique.
+
+    A name collision between the graphs will raise an exception.
+
+    A renaming facility is provided to avoid name collisions.
 
-    Graphs G and H must be disjoint after the renaming takes place,
-    otherwise an exception is raised.
 
     Parameters
     ----------
-    G,H : graph
+    G, H : graph
        A NetworkX graph
 
     rename : tuple , default=(None, None)
@@ -40,14 +42,23 @@ def union(G, H, rename=(None, None), name=None):
     -------
     U : A union graph with the same type as G.
 
+    See Also
+    --------
+    compose
+    :func:`~networkx.Graph.update`
+    disjoint_union
+
     Notes
     -----
-    To force a disjoint union with node relabeling, use
-    disjoint_union(G,H) or convert_node_labels_to integers().
+    To combine graphs that have common nodes, consider compose(G, H)
+    or the method, Graph.update().
 
-    Graph, edge, and node attributes are propagated from G and H
-    to the union graph.  If a graph attribute is present in both
-    G and H the value from H is used.
+    disjoint_union() is similar to union() except that it avoids name clashes
+    by relabeling the nodes with sequential integers.
+
+    Edge and node attributes are propagated from G and H to the union graph.
+    Graph attributes are also propagated, but if they are present in both G and H,
+    then the value from H is used.
 
     Examples
     --------
@@ -59,9 +70,7 @@ def union(G, H, rename=(None, None), name=None):
     >>> U.edges
     EdgeView([('G0', 'G1'), ('G0', 'G2'), ('G1', 'G2'), ('H0', 'H1'), ('H0', 'H3'), ('H1', 'H3'), ('H1', 'H2')])
 
-    See Also
-    --------
-    disjoint_union
+
     """
     if name is not None:
         import warnings
@@ -76,9 +85,9 @@ def union(G, H, rename=(None, None), name=None):
 
 
 def disjoint_union(G, H):
-    """Return the disjoint union of graphs G and H.
+    """Combine graphs G and H. The nodes are assumed to be unique (disjoint).
 
-    This algorithm forces distinct integer node labels.
+    This algorithm automatically relabels nodes to avoid name collisions.
 
     Parameters
     ----------
@@ -89,6 +98,12 @@ def disjoint_union(G, H):
     -------
     U : A union graph with the same type as G.
 
+    See Also
+    --------
+    union
+    compose
+    :func:`~networkx.Graph.update`
+
     Notes
     -----
     A new graph is created, of the same class as G.  It is recommended
@@ -97,9 +112,15 @@ def disjoint_union(G, H):
     The nodes of G are relabeled 0 to len(G)-1, and the nodes of H are
     relabeled len(G) to len(G)+len(H)-1.
 
-    Graph, edge, and node attributes are propagated from G and H
-    to the union graph.  If a graph attribute is present in both
-    G and H the value from H is used.
+    Renumbering forces G and H to be disjoint, so no exception is ever raised for a name collision.
+    To preserve the check for common nodes, use union().
+
+    Edge and node attributes are propagated from G and H to the union graph.
+    Graph attributes are also propagated, but if they are present in both G and H,
+    then the value from H is used.
+
+    To combine graphs that have common nodes, consider compose(G, H)
+    or the method, Graph.update().
 
     Examples
     --------
@@ -277,10 +298,12 @@ def symmetric_difference(G, H):
 
 
 def compose(G, H):
-    """Returns a new graph of G composed with H.
+    """Compose graph G with H by combining nodes and edges into a single graph.
+
+    The node sets and edges sets do not need to be disjoint.
 
-    Composition is the simple union of the node sets and edge sets.
-    The node sets of G and H do not need to be disjoint.
+    Composing preserves the attributes of nodes and edges.
+    Attribute values from H take precedent over attribute values from G.
 
     Parameters
     ----------
@@ -289,17 +312,25 @@ def compose(G, H):
 
     Returns
     -------
-    C: A new graph  with the same type as G
+    C: A new graph with the same type as G
+
+    See Also
+    --------
+    :func:`~networkx.Graph.update`
+    union
+    disjoint_union
 
     Notes
     -----
     It is recommended that G and H be either both directed or both undirected.
-    Attributes from H take precedent over attributes from G.
 
     For MultiGraphs, the edges are identified by incident nodes AND edge-key.
     This can cause surprises (i.e., edge `(1, 2)` may or may not be the same
     in two graphs) if you use MultiGraph without keeping track of edge keys.
 
+    If combining the attributes of common nodes is not desired, consider union(),
+    which raises an exception for name collisions.
+
     Examples
     --------
     >>> G = nx.Graph([(0, 1), (0, 2)])