(nifi-minifi-cpp) 12/22: property trait comments

[ma...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

martinzink pushed a commit to branch minifi_rust_pgp
in repository https://gitbox.apache.org/repos/asf/nifi-minifi-cpp.git

commit fd73ee076264d0086b9bd5f8f2ae112267cf2085
Author: Martin Zink <ma...@apache.org>
AuthorDate: Wed Aug 26 09:50:58 2026 +0200

    property trait comments
---
 minifi_rust/minifi_native/src/api/process_context.rs |  9 ++++++---
 minifi_rust/minifi_native/src/api/property.rs        | 12 ++++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/minifi_rust/minifi_native/src/api/process_context.rs b/minifi_rust/minifi_native/src/api/process_context.rs
index 08b172430..4071dc9c8 100644
--- a/minifi_rust/minifi_native/src/api/process_context.rs
+++ b/minifi_rust/minifi_native/src/api/process_context.rs
@@ -30,14 +30,16 @@ pub trait ProcessContext {
         flow_file: Option<&Self::FlowFile>,
     ) -> Result<Option<String>, MinifiError>;
 
-    fn get_raw_controller_service<Cs, P>(
+    /// Returns the RawControllerService (ControllerService wrapper whose lifetime is managed by the agent)
+    fn get_raw_controller_service<RawCs, P>(
         &self,
         property: &Property<P>,
-    ) -> Result<Option<&Cs>, MinifiError>
+    ) -> Result<Option<&RawCs>, MinifiError>
     where
-        Cs: RawControllerService + ComponentIdentifier + 'static,
+        RawCs: RawControllerService + ComponentIdentifier + 'static,
         P: PropertySchema + ?Sized;
 
+    /// Returns the enabled ControllerService (managed by RawControllerService)
     fn get_controller_service<Cs>(
         &self,
         property: &Property<Cs>,
@@ -45,6 +47,7 @@ pub trait ProcessContext {
     where
         Cs: EnableControllerService + ComponentIdentifier + PropertySchema + 'static;
 
+    /// Returns the enabled type erased ControllerService via the registered ControllerServiceApi
     fn get_controller_service_api<Trait: ?Sized + ControllerServiceApi + PropertySchema>(
         &self,
         property: &Property<Trait>,
diff --git a/minifi_rust/minifi_native/src/api/property.rs b/minifi_rust/minifi_native/src/api/property.rs
index bb8a48db4..f541017ef 100644
--- a/minifi_rust/minifi_native/src/api/property.rs
+++ b/minifi_rust/minifi_native/src/api/property.rs
@@ -126,21 +126,32 @@ impl<P: ?Sized + PropertySchema> Property<P> {
     }
 }
 
+/// Trait required to register Property with the agent
+/// These values will be translated to fill out the
+/// validator, allowed_value, allowed_types, is_required on the agent side
 pub trait PropertySchema {
     const CONSTRAINT: Option<PropertyConstraints>;
     const IS_REQUIRED: bool;
 }
 
+/// The requiredness of the property is enforced via this Option impl
+/// If the property is required it should be registered as Property<T>
+/// If the property is not required it should be registered as Property<Option<T>
 impl<T: PropertySchema> PropertySchema for Option<T> {
     const CONSTRAINT: Option<PropertyConstraints> = T::CONSTRAINT;
     const IS_REQUIRED: bool = false;
 }
 
+/// Trait required to register property as Property<T> or Property<Option<T>
+/// Output type will be the resulting type of context.get_property call
+/// fn parse(s: &str) will be used to create T from the Property
+/// (as all properties are just Strings from the agent's point of view)
 pub trait PropertyType: PropertySchema {
     type Output;
     fn parse(s: &str) -> Result<Self::Output, MinifiError>;
 }
 
+/// Helper trait that handles the parsing and proper error management
 pub trait PropertyValue: PropertySchema {
     type Output;
     fn from_raw(raw: Option<String>, name: &str) -> Result<Self::Output, MinifiError>;
@@ -242,6 +253,7 @@ pub trait GetProperty {
         property: &Property<P>,
     ) -> Result<Option<String>, MinifiError>;
 
+    /// P: PropertyValue which is implemented for T, and Option<T> where T: PropertyType
     fn get_property<P: PropertyValue + ?Sized>(
         &self,
         property: &Property<P>,