Improve model docstrings

netbox/dcim/models/device_components.py

@@ -39,6 +39,9 @@ __all__ = (
 
 
 class ComponentModel(models.Model):
+    """
+    An abstract model inherited by any model which has a parent Device.
+    """
     device = models.ForeignKey(
         to='dcim.Device',
         on_delete=models.CASCADE,
@@ -93,6 +96,14 @@ class ComponentModel(models.Model):
 
 
 class CableTermination(models.Model):
+    """
+    An abstract model inherited by all models to which a Cable can terminate (certain device components, PowerFeed, and
+    CircuitTermination instances). The `cable` field indicates the Cable instance which is terminated to this instance.
+
+    `_cable_peer` is a GenericForeignKey used to cache the far-end CableTermination on the local instance; this is a
+    shortcut to referencing `cable.termination_b`, for example. `_cable_peer` is set or cleared by the receivers in
+    dcim.signals when a Cable instance is created or deleted, respectively.
+    """
     cable = models.ForeignKey(
         to='dcim.Cable',
         on_delete=models.SET_NULL,
@@ -137,7 +148,14 @@ class CableTermination(models.Model):
 
 class PathEndpoint(models.Model):
     """
-    Any object which may serve as the originating endpoint of a CablePath.
+    An abstract model inherited by any CableTermination subclass which represents the end of a CablePath; specifically,
+    these include ConsolePort, ConsoleServerPort, PowerPort, PowerOutlet, Interface, PowerFeed, and CircuitTermination.
+
+    `_path` references the CablePath originating from this instance, if any. It is set or cleared by the receivers in
+    dcim.signals in response to changes in the cable path, and complements the `origin` GenericForeignKey field on the
+    CablePath model. `_path` should not be accessed directly; rather, use the `path` property.
+
+    `connected_endpoint()` is a convenience method for returning the destination of the associated CablePath, if any.
     """
     _path = models.ForeignKey(
         to='dcim.CablePath',

netbox/dcim/models/devices.py

@@ -1162,7 +1162,27 @@ class Cable(ChangeLoggedModel, CustomFieldModel):
 
 class CablePath(models.Model):
     """
-    An array of objects conveying the end-to-end path of one or more Cables.
+    A CablePath instance represents the physical path from an origin to a destination, including all intermediate
+    elements in the path. Every instance must specify an `origin`, whereas `destination` may be null (for paths which do
+    not terminate on a PathEndpoint).
+
+    `path` contains a list of nodes within the path, each represented by a tuple of (type, ID). The first element in the
+    path must be a Cable instance, followed by a pair of pass-through ports. For example, consider the following
+    topology:
+
+                     1                              2                              3
+        Interface A --- Front Port A | Rear Port A --- Rear Port B | Front Port B --- Interface B
+
+    This path would be expressed as:
+
+    CablePath(
+        origin = Interface A
+        destination = Interface B
+        path = [Cable 1, Front Port A, Rear Port A, Cable 2, Rear Port B, Front Port B, Cable 3]
+    )
+
+    `is_active` is set to True only if 1) `destination` is not null, and 2) every Cable within the path has a status of
+    "connected".
     """
     origin_type = models.ForeignKey(
         to=ContentType,