From 9fd96014c7eb90125a30028007ff6b3a7d19bca6 Mon Sep 17 00:00:00 2001
From: Corentin Machu <machu@adacore.com>
Date: Fri, 26 Jul 2024 13:23:23 +0200
Subject: [PATCH] Add rapidflux macros documentation

Ref. eng/recordflux/RecordFlux#1741
---
 rapidflux/src/utils.rs | 67 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/rapidflux/src/utils.rs b/rapidflux/src/utils.rs
index b6f372fb6..2a16456e1 100644
--- a/rapidflux/src/utils.rs
+++ b/rapidflux/src/utils.rs
@@ -1,3 +1,19 @@
+/// Enable pickling of a Python class.
+///
+/// This macro implements `__getstate__` and `__setstate__` for the given types.
+/// The serialization is using `bincode` to serialize and deserialize Rust objects.
+///
+/// # Examples
+///
+/// ```rust
+/// // in `foo.rs`
+/// use pyo3::prelude::*;
+///
+/// #[pyclass]
+/// struct Dummy;
+///
+/// impl_states!(Dummy);
+/// ```
 #[macro_export]
 macro_rules! impl_states {
     ($( $name:ty ),* $(,)?) => {
@@ -15,6 +31,24 @@ macro_rules! impl_states {
     };
 }
 
+/// Register classes in a submodule.
+///
+/// This macro generate a `register_<module name>_module` function that is used by the
+/// `register_submodule` function later to add a submodule in `rapidflux`.
+///
+/// # Examples
+///
+/// ```rust
+/// // in `foo.rs`
+/// use pyo3::prelude::*;
+///
+/// #[pyclass]
+/// pub struct Foo;
+/// #[pyclass]
+/// pub struct Bar;
+///
+/// register_submodule_classes!(foo, [Foo, Bar]);
+/// ```
 #[macro_export]
 macro_rules! register_submodule_classes {
     ($module_name:ident, [$($class_name:ident),+ $(,)?] $(,)?) => {
@@ -39,6 +73,21 @@ macro_rules! register_submodule_classes {
     };
 }
 
+/// Register functions in a submodule.
+///
+/// Works like `register_submodule_classes` but takes one or more functions instead.
+///
+/// # Examples
+///
+/// ```rust
+/// // in `foo.rs`
+/// use pyo3::prelude::*;
+///
+/// fn bar() {}
+/// fn baz() {}
+///
+/// register_submodule_functions!(foo, [bar, baz]);
+/// ```
 #[macro_export]
 macro_rules! register_submodule_functions {
     ($module_name:ident, [$($fn_name:ident),+ $(,)?] $(,)?) => {
@@ -63,6 +112,24 @@ macro_rules! register_submodule_functions {
     };
 }
 
+/// Register a submodule in `rflx.rapidflux`.
+///
+/// This macro call the `register_<module name>_module` function to initialize the submodule and
+/// then add the module to `rflx.rapidflux` as a submodule.
+///
+/// # Examples
+///
+/// ```rust
+/// // in `lib.rs`
+/// use pyo3::prelude::*;
+///
+/// #[pymodule]
+/// fn rapidflux(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
+///     // ...
+///     register_submodule!(foo, py, m);
+///     register_submodule!(bar, py, m);
+/// }
+/// ```
 #[macro_export]
 macro_rules! register_submodule {
     ($name:ident, $py:ident, $parent_module:ident) => {