DOC: refactor Dual docs

docs/source/api/rateslib.dual.Dual.rst

@@ -41,5 +41,14 @@ Dual
 
    .. rubric:: Methods Summary
 
-   .. include:: rateslib.dual.Dual.to_json.rst
-   .. include:: rateslib.dual.Dual.vars_from.rst
+   .. autosummary::
+
+      ~Dual.ptr_eq
+      ~Dual.to_json
+      ~Dual.vars_from
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: rateslib.dual.Dual.ptr_eq
+   .. automethod:: rateslib.dual.Dual.to_json
+   .. automethod:: rateslib.dual.Dual.vars_from

src/dual/dual_py.rs

@@ -50,6 +50,44 @@ impl Dual {
         Dual::try_new(real, vars, dual)
     }
 
+    /// Create a :class:`~rateslib.dual.Dual` object with ``vars`` linked with another.
+    ///
+    /// Parameters
+    /// ----------
+    /// other: Dual
+    ///     The other `Dual` from which `vars` are linked.
+    /// real: float
+    ///     The real coefficient of the dual number.
+    /// vars: list[str]
+    ///     The labels of the variables for which to record derivatives. If empty,
+    ///     the dual number represents a constant, equivalent to a float.
+    /// dual: list[float]
+    ///     First derivative information contained as coefficient of linear manifold.
+    ///     Defaults to an array of ones the length of ``vars`` if empty.
+    ///
+    /// Returns
+    /// -------
+    /// Dual
+    ///
+    /// Notes
+    /// -----
+    /// Variables are constantly checked when operations are performed between dual numbers. In Rust the variables
+    /// are stored within an ARC pointer. It is much faster to check the equivalence of two ARC pointers than if the elements
+    /// within a variables Set, say, are the same *and* in the same order. This method exists to create dual data types
+    /// with shared ARC pointers directly.
+    ///
+    /// .. ipython:: python
+    ///
+    ///    from rateslib import Dual
+    ///
+    ///    x1 = Dual(1.0, ["x"], [])
+    ///    x2 = Dual(2.0, ["x"], [])
+    ///    # x1 and x2 have the same variables (["x"]) but it is a different object
+    ///    x1.ptr_eq(x2)
+    ///
+    ///    x3 = Dual.vars_from(x1, 3.0, ["x"], [])
+    ///    # x3 contains shared object variables with x1
+    ///    x1.ptr_eq(x3)
     #[staticmethod]
     fn vars_from(other: &Dual, real: f64, vars: Vec<String>, dual: Vec<f64>) -> PyResult<Self> {
         Dual::try_new_from(other, real, vars, dual)
@@ -97,6 +135,16 @@ impl Dual {
         ))
     }
 
+    /// Evaluate if the ARC pointers of two `Dual` data types are equivalent.
+    ///
+    /// Parameters
+    /// ----------
+    /// other: Dual
+    ///     The comparison object.
+    ///
+    /// Returns
+    /// -------
+    /// bool
     #[pyo3(name = "ptr_eq")]
     fn ptr_eq_py(&self, other: &Dual) -> PyResult<bool> {
         Ok(Arc::ptr_eq(self.vars(), other.vars()))
@@ -288,6 +336,11 @@ impl Dual {
     }
 
     // JSON
+    /// Create a JSON string representation of the object.
+    ///
+    /// Returns
+    /// -------
+    /// str
     #[pyo3(name = "to_json")]
     fn to_json_py(&self) -> PyResult<String> {
         match DeserializedObj::Dual(self.clone()).to_json() {