From 375e3a18287738166c16555efe0ae8a82b2b4997 Mon Sep 17 00:00:00 2001
From: Kory Draughn <korydraughn@renci.org>
Date: Wed, 10 Jul 2024 10:20:31 -0400
Subject: [PATCH] [#7870] Improve documentation for atomic acls/metadata
 microservices.

---
 .../src/atomic_apply_acl_operations.cpp       | 21 +++++++++++++++++
 .../src/atomic_apply_metadata_operations.cpp  | 23 +++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/plugins/microservices/src/atomic_apply_acl_operations.cpp b/plugins/microservices/src/atomic_apply_acl_operations.cpp
index 27305d3c35..c7e58ba5bd 100644
--- a/plugins/microservices/src/atomic_apply_acl_operations.cpp
+++ b/plugins/microservices/src/atomic_apply_acl_operations.cpp
@@ -86,6 +86,7 @@ auto plugin_factory() -> irods::ms_table_entry*
 /// \p _json_input must have the following JSON structure:
 /// \code{.js}
 /// {
+///   "admin_mode": boolean,
 ///   "logical_path": string,
 ///   "operations": [
 ///     {
@@ -126,6 +127,26 @@ auto plugin_factory() -> irods::ms_table_entry*
 /// \retval 0        On success.
 /// \retval non-zero On failure.
 ///
+/// \b Example
+/// \code{.py}
+/// # The collection to apply the ACL operations to.
+/// *lpath = '/tempZone/home/alice';
+///
+/// # The JSON string holding ACL operations to apply.
+/// *json_input = '{"logical_path": "*lpath", "operations": [{"entity_name": "bob", "acl": "read"}]}';
+///
+/// # If the microservice fails, a JSON string containing details about what happened will be
+/// # stored in this variable.
+/// *json_output = ''
+///
+/// *ec = errorcode(msi_atomic_apply_acl_operations(*json_input, *json_output));
+/// if (*ec < 0) {
+///     # The operation failed.
+///     # Inspect JSON output (using JSON microservices) to determine what happened.
+///     writeLine('serverLog', 'JSON output = [*json_output]');
+/// }
+/// \endcode
+///
 /// \since 4.2.9
 auto msi_atomic_apply_acl_operations(msParam_t* _json_input, msParam_t* _json_output, ruleExecInfo_t* _rei) -> int;
 #endif // IRODS_FOR_DOXYGEN
diff --git a/plugins/microservices/src/atomic_apply_metadata_operations.cpp b/plugins/microservices/src/atomic_apply_metadata_operations.cpp
index 9bebb40719..9a070b59ce 100644
--- a/plugins/microservices/src/atomic_apply_metadata_operations.cpp
+++ b/plugins/microservices/src/atomic_apply_metadata_operations.cpp
@@ -92,6 +92,7 @@ auto plugin_factory() -> irods::ms_table_entry*
 /// \p _json_input must have the following JSON structure:
 /// \code{.js}
 /// {
+///   "admin_mode": boolean,
 ///   "entity_name": string,
 ///   "entity_type": string,
 ///   "operations": [
@@ -144,6 +145,28 @@ auto plugin_factory() -> irods::ms_table_entry*
 /// \retval 0        On success.
 /// \retval non-zero On failure.
 ///
+/// \b Example
+/// \code{.py}
+/// # The JSON string holding the single metadata operation to apply to the resource.
+/// # This will be used to construct the final form of the JSON input.
+/// *op = '{"operation": "add", "attribute": "age", "value": "36"}';
+///
+/// # This is the complete form of the JSON string that will be passed to the microservice.
+/// # Pay close attention to the construction of the "operations" property.
+/// *json_input = '{"entity_name": "alice", "entity_type": "user", "operations": [*op]}';
+///
+/// # If the microservice fails, a JSON string containing details about what happened will be
+/// # stored in this variable.
+/// *json_output = ''
+///
+/// *ec = errorcode(msi_atomic_apply_metadata_operations(*json_input, *json_output));
+/// if (*ec < 0) {
+///     # The operation failed.
+///     # Inspect JSON output (using JSON microservices) to determine what happened.
+///     writeLine('serverLog', 'JSON output = [*json_output]');
+/// }
+/// \endcode
+///
 /// \since 4.2.8
 auto msi_atomic_apply_metadata_operations(msParam_t* _json_input, msParam_t* _json_output, ruleExecInfo_t* _rei) -> int;
 #endif // IRODS_FOR_DOXYGEN