From 348071223b52becf7c2d09c071ed399f289045f7 Mon Sep 17 00:00:00 2001 From: Antal Spector-Zabusky Date: Fri, 28 Jun 2024 16:07:08 -0700 Subject: [PATCH] feat: add documentation to all generated methods --- src/lib.rs | 3 +++ src/traits.rs | 10 ++++++++ src/wrappers.rs | 63 ++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 75 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 29356cb..250ad7c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -198,6 +198,7 @@ impl PyWrapperMut for T where T: PyWrapper + AsMut {} /// } /// /// create_init_submodule! { +/// /// Initialize this module and all its submodules /// classes: [ PyCoolString ], /// errors: [ IOError ], /// funcs: [ do_nothing ], @@ -212,12 +213,14 @@ impl PyWrapperMut for T where T: PyWrapper + AsMut {} #[macro_export] macro_rules! create_init_submodule { ( + $(#[$meta:meta])* $(classes: [ $($class: ty),+ ],)? $(consts: [ $($const: ident),+ ],)? $(errors: [ $($error: ty),+ ],)? $(funcs: [ $($func: path),+ ],)? $(submodules: [ $($mod_name: literal: $init_submod: path),+ ],)? ) => { + $(#[$meta])* pub(crate) fn init_submodule(_name: &str, _py: $crate::pyo3::Python, m: &$crate::pyo3::types::PyModule) -> $crate::pyo3::PyResult<()> { $($( m.add_class::<$class>()?; diff --git a/src/traits.rs b/src/traits.rs index d610cc1..6febb7e 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -25,6 +25,8 @@ macro_rules! impl_compare { ($name: ident) => { #[$crate::pyo3::pymethods] impl $name { + /// Implements all the Python comparison operators in terms of the + /// Rust [`PartialOrd`](std::cmp::PartialOrd) instance. #![allow(clippy::use_self)] pub fn __richcmp__(&self, object: &Self, cmp: $crate::pyo3::basic::CompareOp) -> bool { let result = ::std::cmp::PartialOrd::partial_cmp(self, object); @@ -59,6 +61,8 @@ macro_rules! impl_hash { ($name: ident) => { #[$crate::pyo3::pymethods] impl $name { + /// Implements `__hash__` for Python in terms of the Rust + /// [`Hash`](std::hash::Hash) instance. pub fn __hash__(&self) -> i64 { let mut hasher = ::std::collections::hash_map::DefaultHasher::new(); ::std::hash::Hash::hash($crate::PyWrapper::as_inner(self), &mut hasher); @@ -73,6 +77,8 @@ macro_rules! impl_hash { #[macro_export] macro_rules! impl_repr { ($name: ident) => { + /// Implements `__repr__` for Python in terms of the Rust + /// [`Debug`](std::fmt::Debug) instance. #[$crate::pyo3::pymethods] impl $name { pub fn __repr__(&self) -> String { @@ -86,6 +92,8 @@ macro_rules! impl_repr { #[macro_export] macro_rules! impl_str { ($name: ident) => { + /// Implements `__str__` for Python in terms of the Rust + /// [`Display`](std::fmt::Display) instance. #[$crate::pyo3::pymethods] impl $name { pub fn __str__(&self) -> String { @@ -124,6 +132,8 @@ macro_rules! impl_parse { ($name: ident) => { #[$crate::pyo3::pymethods] impl $name { + /// Implements a static `parse` method for Python in terms of the + /// Rust [`FromStr`](std::str::FromStr) instance. #[staticmethod] pub fn parse(input: &str) -> $crate::pyo3::PyResult { ::from_str(input) diff --git a/src/wrappers.rs b/src/wrappers.rs index afe9ad9..d524e01 100644 --- a/src/wrappers.rs +++ b/src/wrappers.rs @@ -453,6 +453,13 @@ macro_rules! py_wrap_struct { impl $name { #![allow(clippy::use_self)] + #[doc = concat!( + r"Create a new [`", + stringify!($name), + r"`] from Python arguments; corresponds to `", + $($py_class, r".",)? + r"__new__()` in Python" + )] #[new] pub fn new(py: $crate::pyo3::Python, input: $crate::pyo3::Py<$crate::pyo3::PyAny>) -> $crate::pyo3::PyResult { use $crate::pyo3::FromPyObject; @@ -579,6 +586,15 @@ macro_rules! py_wrap_union_enum { $crate::paste::paste! { #[$crate::pyo3::pymethods] impl $name { + #[doc = concat!( + r"The Python wrapper for [`", + stringify!($rs_enum), + r"::", + stringify!($variant), + r"`], creating a [`", + stringify!($name), + r"and taking a Python argument." + )] #[staticmethod] pub fn [< from_ $variant_name >](py: $crate::pyo3::Python, inner: $crate::private_ultimate_type!($($convert),+)) -> $crate::pyo3::PyResult { let inner = &inner; @@ -593,6 +609,10 @@ macro_rules! py_wrap_union_enum { $crate::paste::paste! { #[$crate::pyo3::pymethods] impl $name { + #[doc = concat!( + r"Create a new [`", stringify!($name), r"`] wrapping a ", + r"[`", stringify!($rs_enum), r"::", stringify!($variant), "`]." + )] #[staticmethod] pub fn [< new_ $variant_name >]() -> Self { Self::from($rs_enum::$variant) @@ -632,6 +652,13 @@ macro_rules! py_wrap_union_enum { $crate::paste::paste! { #[$crate::pyo3::pymethods] impl $name { + #[doc = concat!( + r"Create a new [`", + stringify!($name), + r"`] from a Python argument; corresponds to `", + $($py_class, r".",)? + r"__new__()` in Python" + )] #[new] pub fn new(py: $crate::pyo3::Python, input: &$crate::pyo3::PyAny) -> $crate::pyo3::PyResult { $( @@ -655,6 +682,15 @@ macro_rules! py_wrap_union_enum { )) } + #[doc = concat!( + r"Directly return the Python version of the variant discriminant wrapped by this ", + r"value; ", + r"i.e., performs the match `", + stringify!($rs_inner), + r"::Variant(x) => x` for every variant constructor in [`", + stringify!($rs_inner), + r"`]" + )] #[allow(unreachable_code, unreachable_pattern)] pub fn inner(&self, py: $crate::pyo3::Python) -> $crate::pyo3::PyResult<$crate::pyo3::Py<$crate::pyo3::PyAny>> { match &self.0 { @@ -674,15 +710,31 @@ macro_rules! py_wrap_union_enum { } $( + #[doc = concat!( + r"Tests if this [`", stringify!($name), r"`] ", + r"wraps a [`", stringify!($rs_inner), r"::", stringify!($variant_name), "`] value" + )] const fn [< is_ $variant_name >](&self) -> bool { $crate::py_wrap_union_enum!(@is_variant self, $rs_inner, $variant $(($(=> $convert)+))?) } $( + #[doc = concat!( + r"Returns `x` if this [`", stringify!($name), r"`] ", + r"wraps a `", stringify!($rs_inner), r"::", stringify!($variant_name), "`(x); ", + r"otherwise returns (Python) `None`. On the Rust side, this corresponds to ", + r"either `Some(x)` or [`None`]." + )] fn [< as_ $variant_name >](&self, py: $crate::pyo3::Python) -> Option<$crate::private_ultimate_type!($($convert),+)> { self.[< to_ $variant_name >](py).ok() } + #[doc = concat!( + r"Returns `x` if this [`", stringify!($name), r"`] ", + r"wraps a `", stringify!($rs_inner), r"::", stringify!($variant_name), "`(x); ", + r"otherwise raises a `ValueError`. On the Rust side, this corresponds to ", + r"either `Ok(x)` or `Err(...)`." + )] fn [< to_ $variant_name >](&self, py: $crate::pyo3::Python) -> $crate::pyo3::PyResult<$crate::private_ultimate_type!($($convert),+)> { if let $rs_inner::$variant(inner) = &self.0 { $crate::private_intermediate_to_python!(py, &inner $(=> $convert)+) @@ -721,7 +773,8 @@ macro_rules! py_wrap_union_enum { /// ``` #[macro_export] macro_rules! wrap_error { - ($name: ident ($inner: ty)$(;)?) => { + ($(#[$meta: meta])* $name: ident ($inner: ty)$(;)?) => { + $(#[$meta])* #[derive(Debug)] #[repr(transparent)] pub struct $name($inner); @@ -844,6 +897,10 @@ macro_rules! py_wrap_data_struct { #[rigetti_pyo3::pyo3::pymethods] impl $name { $( + #[doc = concat!( + r"Get the ", stringify!($field_name), r" field from Python. ", + r"Annotated with `@property`." + )] #[getter] fn [< get_ $field_name >](&self, py: $crate::pyo3::Python<'_>) -> $crate::pyo3::PyResult<$crate::private_ultimate_type!($($convert),+)> { use $crate::{PyWrapper, ToPython}; @@ -851,6 +908,10 @@ macro_rules! py_wrap_data_struct { $crate::private_intermediate_to_python!(py, &inner $(=> $convert)+) } + #[doc = concat!( + r"Set the ", stringify!($field_name), r" field from Python. ", + r"Annotated with `@", stringify!($field_name), r".setter`." + )] #[setter] fn [< set_ $field_name >](&mut self, py: $crate::pyo3::Python<'_>, from: $crate::private_ultimate_type!($($convert),+)) -> $crate::pyo3::PyResult<()> { use $crate::{PyTryFrom, PyWrapperMut};