From c97b64b36b93209c8f6ac287e81ddebb0723ac27 Mon Sep 17 00:00:00 2001 From: Matthew Broadway Date: Sat, 23 Nov 2024 01:22:11 +0000 Subject: [PATCH] documentation changes --- src/impl_/pyclass.rs | 4 ++-- src/impl_/trampoline.rs | 4 ++-- src/instance.rs | 1 - src/pycell/layout.rs | 24 ++++++++++++------------ src/type_object.rs | 2 +- 5 files changed, 17 insertions(+), 18 deletions(-) diff --git a/src/impl_/pyclass.rs b/src/impl_/pyclass.rs index e9a958792bc..965871d33de 100644 --- a/src/impl_/pyclass.rs +++ b/src/impl_/pyclass.rs @@ -1146,8 +1146,8 @@ impl PyClassThreadChecker for ThreadCheckerImpl { ) )] pub trait PyClassBaseType: Sized { - /// A struct that describes the memory layout of a `*mut ffi:PyObject` with the type of `Self`. - /// Only valid when `::OPAQUE` is false. + /// A struct that describes the memory layout of a `ffi:PyObject` with the type of `Self`. + /// Only valid when `::OPAQUE` is `false`. type StaticLayout: PyLayout; type BaseNativeType: PyTypeInfo; type RecursiveOperations: PyObjectRecursiveOperations; diff --git a/src/impl_/trampoline.rs b/src/impl_/trampoline.rs index 3af8eaa4a07..32416af6a02 100644 --- a/src/impl_/trampoline.rs +++ b/src/impl_/trampoline.rs @@ -122,8 +122,8 @@ trampolines!( pub fn unaryfunc(slf: *mut ffi::PyObject) -> *mut ffi::PyObject; ); -// tp_init should return 0 on success and -1 on error -// https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_init +/// `tp_init` should return 0 on success and -1 on error. +/// [docs](https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_init) #[inline] pub unsafe fn initproc( slf: *mut ffi::PyObject, diff --git a/src/instance.rs b/src/instance.rs index eb0168fb4fe..a7b138a2a8b 100644 --- a/src/instance.rs +++ b/src/instance.rs @@ -1286,7 +1286,6 @@ where /// /// This is available if the class is [`frozen`][macro@crate::pyclass] and [`Sync`]. /// - /// /// # Examples /// /// ``` diff --git a/src/pycell/layout.rs b/src/pycell/layout.rs index a734154231d..f651f0f6b13 100644 --- a/src/pycell/layout.rs +++ b/src/pycell/layout.rs @@ -36,7 +36,7 @@ pub(crate) struct PyClassObjectContents { pub(crate) value: ManuallyDrop>, pub(crate) borrow_checker: ::Storage, pub(crate) thread_checker: T::ThreadChecker, - /// A pointer to a [ffi::PyObject]` if `T` is annotated with `#[pyclass(dict)]` and a zero-sized field otherwise. + /// A pointer to a [ffi::PyObject] if `T` is annotated with `#[pyclass(dict)]` and a zero-sized field otherwise. pub(crate) dict: T::Dict, /// A pointer to a [ffi::PyObject] if `T` is annotated with `#[pyclass(weakref)]` and a zero-sized field otherwise. pub(crate) weakref: T::WeakRef, @@ -62,7 +62,7 @@ impl PyClassObjectContents { } } -/// Functions for working with `PyObjects` recursively by re-interpreting the object +/// Functions for working with [ffi::PyObject]s recursively by re-interpreting the object /// as being an instance of the most derived class through each base class until /// the `BaseNativeType` is reached. /// @@ -86,8 +86,8 @@ pub trait PyObjectRecursiveOperations { /// Cleanup then free the memory for `obj`. /// /// # Safety - /// - slf must be a valid pointer to an instance of a T or a subclass. - /// - slf must not be used after this call (as it will be freed). + /// - `obj` must be a valid pointer to an instance of a `T` or a subclass. + /// - `obj` must not be used after this call (as it will be freed). unsafe fn deallocate(py: Python<'_>, obj: *mut ffi::PyObject); } @@ -154,8 +154,8 @@ impl PyObjectRecursiveOperations /// [tp_dealloc docs](https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_dealloc) /// /// # Safety - /// - obj must be a valid pointer to an instance of the type at `type_ptr` or a subclass. - /// - obj must not be used after this call (as it will be freed). + /// - `obj` must be a valid pointer to an instance of the type at `type_ptr` or a subclass. + /// - `obj` must not be used after this call (as it will be freed). unsafe fn deallocate(py: Python<'_>, obj: *mut ffi::PyObject) { // the `BaseNativeType` of the object let type_ptr = ::type_object_raw(py); @@ -208,7 +208,7 @@ impl PyObjectRecursiveOperations } } -/// Utilities for working with `PyObject` objects that utilise [PEP 697](https://peps.python.org/pep-0697/). +/// Utilities for working with [ffi::PyObject] objects that utilise [PEP 697](https://peps.python.org/pep-0697/). #[doc(hidden)] pub(crate) mod opaque_layout { #[cfg(Py_3_12)] @@ -255,7 +255,7 @@ pub(crate) mod opaque_layout { } } -/// Utilities for working with `PyObject` objects that utilise the standard layout for python extensions, +/// Utilities for working with [ffi::PyObject] objects that utilise the standard layout for python extensions, /// where the base class is placed at the beginning of a `repr(C)` struct. #[doc(hidden)] pub(crate) mod static_layout { @@ -266,7 +266,7 @@ pub(crate) mod static_layout { use super::PyClassObjectContents; - // The layout of a `PyObject` that uses the static layout + // The layout of a [ffi::PyObject] that uses the static layout #[repr(C)] pub struct PyStaticClassLayout { pub(crate) ob_base: ::StaticLayout, @@ -275,7 +275,7 @@ pub(crate) mod static_layout { unsafe impl PyLayout for PyStaticClassLayout {} - /// Base layout of PyClassObject with a known sized base type. + /// Base layout of [PyClassObject] with a known sized base type. /// Corresponds to [PyObject](https://docs.python.org/3/c-api/structures.html#c.PyObject) from the C API. #[doc(hidden)] #[repr(C)] @@ -1698,8 +1698,8 @@ mod opaque_fail_tests { fn __init__(&mut self, _args: &Bound<'_, PyTuple>, _kwargs: Option<&Bound<'_, PyDict>>) {} } - /// PyType uses the opaque layout. Explicitly using `#[pyclass(opaque)]` can be caught at compile time - /// but it is possible to create a pyclass that uses the opaque layout by extending an opaque native type. + /// PyType uses the opaque layout. While explicitly using `#[pyclass(opaque)]` can be caught at compile time, + /// it is also possible to create a pyclass that uses the opaque layout by extending an opaque native type. #[test] #[should_panic( expected = "The opaque object layout (used by pyo3::pycell::layout::opaque_fail_tests::Metaclass) is not supported until python 3.12" diff --git a/src/type_object.rs b/src/type_object.rs index 13b7c3c732e..eacf9e04cf0 100644 --- a/src/type_object.rs +++ b/src/type_object.rs @@ -6,7 +6,7 @@ use crate::types::{PyAny, PyType}; use crate::{ffi, Bound, Python}; /// `T: PyNativeType` represents that `T` is a struct representing a 'native python class'. -/// a 'native class' is a wrapper around a `ffi::PyTypeObject` that is defined by the python +/// a 'native class' is a wrapper around a [ffi::PyTypeObject] that is defined by the python /// API such as `PyDict` for `dict`. /// /// This trait is intended to be used internally.