From 36b5f900edcee17e468d4723dc329c5014aa9084 Mon Sep 17 00:00:00 2001
From: Satvik Mishra <89024979+SatvikMishra08@users.noreply.github.com>
Date: Sun, 27 Sep 2026 14:17:53 +0000
Subject: [PATCH] docs: document when Bound::new returns Err

Closes #5485
---
 src/instance.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/instance.rs b/src/instance.rs
index 244a3df6f46..57e81bfc9a1 100644
--- a/src/instance.rs
+++ b/src/instance.rs
@@ -79,6 +79,20 @@ where
 {
     /// Creates a new instance `Bound<T>` of a `#[pyclass]` on the Python heap.
     ///
+    /// Construction goes through [`PyClassInitializer`] and the `create_class_object`
+    /// path used for `#[pyclass]` types.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err` when Python object construction fails. Typical cases include:
+    ///
+    /// - a base type without `tp_new`, which raises [`PyTypeError`](crate::exceptions::PyTypeError)
+    ///   (`"base type without tp_new"`);
+    /// - `tp_new` or allocation returning a null pointer, in which case the active Python
+    ///   exception is fetched via [`PyErr::fetch`](crate::PyErr::fetch) (commonly
+    ///   [`MemoryError`](crate::exceptions::PyMemoryError), or another exception raised during
+    ///   initialization).
+    ///
     /// # Examples
     ///
     /// ```rust