Add some documentation

Author: BCSol

rclrs/src/parameter.rs

@@ -14,7 +14,6 @@ use crate::vendor::rcl_interfaces::msg::rmw::{ParameterType, ParameterValue as R
 use crate::{
     call_string_getter_with_rcl_node, rcl_bindings::*, Node, RclrsError, ENTITY_LIFECYCLE_MUTEX,
 };
-use std::default;
 use std::{
     collections::{btree_map::Entry, BTreeMap},
     fmt::Debug,

rclrs/src/parameter/structured.rs

@@ -1,29 +1,74 @@
 use crate::NodeState;
 
+/// Marker trait for implementing [`StructuredParameters`] where a default value cannot be specified.
+/// This is usually the case for container types, that are not represented by any actual parameter.
 pub enum DefaultForbidden {}
 
-pub trait StructuredParametersMeta<T>: Sized {
-    fn declare_structured_(
+/// Types implementing this trait can delcare their parameters with[`NodeState::declare_parameters`].
+/// The trait can be automatically derived using [`rclrs_proc_macros`] if:
+/// - if the type is a struct
+/// - all attributes implement [`StructuredParameters`]
+pub trait StructuredParameters: Sized {
+    /// Declares all parameters in ros node.
+    ///
+    /// # Parameters
+    ///
+    /// - `node`: The ros node to declare parameters for.
+    /// - `name`: The name of the parameter. Nested parameters are recursively declared with "{name}.{field_name}" if the name is not empty else "{field_name}".
+    /// - `default`: The default value for the paramter.
+    /// - `description` The description of the parameter
+    ///
+    /// # Returns
+    ///
+    /// [`Result`] containing the declared structured parameters or [`crate::DeclarationError`]
+    fn declare_structured<T>(
         node: &NodeState,
         name: &str,
         default: Option<T>,
         description: impl Into<std::sync::Arc<str>>,
-    ) -> core::result::Result<Self, crate::DeclarationError>;
+    ) -> core::result::Result<Self, crate::DeclarationError>
+    where
+        Self: StructuredParametersMeta<T>,
+    {
+        Self::declare_structured_(node, name, default, description)
+    }
 }
 
-pub trait StructuredParameters: Sized {
-    fn declare_structured<T>(
+/// Helper trait to unify the default value type with generic container types like
+/// - [`crate::MandatoryParameter<T>`]
+/// - [`crate::OptionalParameter<T>`]
+/// - [`crate::ReadOnlyParameter<T>`]
+///
+/// In these cases the [`Self`] != [`T`] and forces the usage of a generic trait.
+/// However, a generic trait also requires annotating this default value in the derive macro.
+/// For the container based structured parameters [`T`] is always [`DefaultForbidden`]
+/// and therefore we can hide this form the trait + macro by using this helper trait.
+/// The previously mentioned leaf types that actually hold parameters, are to be implemented manually anyway.
+///
+pub trait StructuredParametersMeta<T>: Sized {
+    /// See [`StructuredParameters::declare_structured`]
+    fn declare_structured_(
         node: &NodeState,
         name: &str,
         default: Option<T>,
         description: impl Into<std::sync::Arc<str>>,
-    ) -> core::result::Result<Self, crate::DeclarationError>
+    ) -> core::result::Result<Self, crate::DeclarationError>;
+}
+
+impl NodeState {
+    /// Declares all nested parameters of the [`StructuredParameters`].
+    /// Parameter naming recursively follows "`name`.`field_name`" or "`field_name`" if the initial `name` is empty.
+    pub fn declare_parameters<T, T0>(
+        &self,
+        name: &str,
+    ) -> core::result::Result<T, crate::DeclarationError>
     where
-        Self: StructuredParametersMeta<T>,
+        T: StructuredParameters + StructuredParametersMeta<T0>,
     {
-        Self::declare_structured_(node, name, default, description)
+        T::declare_structured(self, name, None, "")
     }
 }
+
 impl<T: crate::ParameterVariant> StructuredParameters for crate::MandatoryParameter<T> {}
 impl<T: crate::ParameterVariant> StructuredParametersMeta<T> for crate::MandatoryParameter<T> {
     fn declare_structured_(
@@ -73,18 +118,7 @@ impl<T: crate::ParameterVariant> StructuredParametersMeta<T> for crate::Optional
     }
 }
 
-impl NodeState {
-    pub fn declare_parameters<T, T0>(
-        &self,
-        name: &str,
-    ) -> core::result::Result<T, crate::DeclarationError>
-    where
-        T: StructuredParameters + StructuredParametersMeta<T0>,
-    {
-        T::declare_structured(self, name, None, "")
-    }
-}
-
+#[cfg(test)]
 mod tests {
     use std::sync::Arc;
 

rclrs_proc_macros/src/impl.rs

@@ -1,8 +1,6 @@
-use std::default;
-
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{Data, DeriveInput, Expr, Lit, Meta};
+use syn::{DeriveInput, Expr};
 
 pub(crate) fn derive_struct_parameters(input: DeriveInput) -> syn::Result<TokenStream> {
     let ident = input.ident;
@@ -37,7 +35,7 @@ pub(crate) fn derive_struct_parameters(input: DeriveInput) -> syn::Result<TokenS
                         description = Some(meta.value()?.parse()?);
                         Ok(())
                     } else {
-                        let err = format!("Unknown key: {:?}", &meta.path);
+                        let err = format!("Unknown key: {:?}", &meta.path.get_ident());
                         syn::Result::Err(syn::Error::new_spanned(meta.path, err))
                     }
                 })?;