s4:dsdb:audit_log clean up doc comments

Signed-off-by: Gary Lockyer <gary@catalyst.net.nz>
Reviewed-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>

diff --git a/source4/dsdb/samdb/ldb_modules/audit_log.c b/source4/dsdb/samdb/ldb_modules/audit_log.c
index 92570e2f4ec7276d304893fe2a54343a74a80bf1..c944a84b36080495c17107de0ef1d52fef1d58c7 100644 (file)
--- a/source4/dsdb/samdb/ldb_modules/audit_log.c
+++ b/source4/dsdb/samdb/ldb_modules/audit_log.c
@@ -102,6 +102,8 @@ struct audit_private {
  * Does the message contain a change to one of the password attributes? The
  * password attributes are defined in DSDB_PASSWORD_ATTRIBUTES
  *
+ * @param[in] message the ldb_message to examine
+ *
  * @return true if the message contains a password attribute
  *
  */
@@ -143,6 +145,8 @@ static bool has_password_changed(const struct ldb_message *message)
  * database -- a message setting an attribute to its current
  * value will still be logged as a change.
  *
+ * @param[in] message the ldb_message to examine
+ *
  * @return true if the message contains authentication information
  */
 static bool has_authentication_information_changed(
@@ -169,8 +173,8 @@ static bool has_authentication_information_changed(
  * This routine assumes that the request contains password attributes and that the
  * password ACL checks have been performed by acl.c
  *
- * @param request the ldb_request to inspect
- * @param reply the ldb_reply, will contain the password controls
+ * @param[in] request the ldb_request to inspect
+ * @param[in] reply   the ldb_reply, will contain the password controls
  *
  * @return The windows event code.
  */
@@ -209,8 +213,8 @@ static enum event_id_type get_password_windows_event_id(
  * routine assumes that the request contains password attributes and that the
  * password ACL checks have been performed by acl.c
  *
- * @param request the ldb_request to inspect
- * @param reply the ldb_reply, will contain the password controls
+ * @param[in] request the ldb_request to inspect
+ * @param[in] reply   the ldb_reply, will contain the password controls
  *
  * @return "Change" if the password is being changed.
  *         "Reset"  if the password is being reset.
@@ -249,12 +253,12 @@ static const char *get_password_action(
  *
  * Generate a JSON object detailing an ldb operation.
  *
- * @param module the ldb module
- * @param request the request
- * @param reply the result of the operation.
+ * @param[in] module  the ldb module
+ * @param[in] request the request
+ * @param[in] reply   the result of the operation.
  *
  * @return the generated JSON object, should be freed with json_free.
- *
+ *        in the event of an error it will return json_empty_object
  *
  */
 static struct json_object operation_json(
@@ -393,12 +397,12 @@ failure:
  *
  * Generate a JSON object detailing a replicated update
  *
- * @param module the ldb module
- * @param request the request
- * @paran reply the result of the operation
+ * @param[in] module  the ldb module
+ * @param[in] request the request
+ * @param[in] reply   the result of the operation
  *
  * @return the generated JSON object, should be freed with json_free.
- *         NULL if there was an error generating the message.
+ *        in the event of an error it will return json_empty_object
  *
  */
 static struct json_object replicated_update_json(
@@ -511,12 +515,13 @@ failure:
  *
  * Generate a JSON object detailing a password change.
  *
- * @param module the ldb module
- * @param request the request
- * @param reply the result/response
- * @param status the status code returned for the underlying ldb operation.
+ * @param[in] module            the ldb module
+ * @param[in] request           the request
+ * @param[in] reply             the result/response
+ * @param[in] auth_info_changed was authentication information changed?
  *
- * @return the generated JSON object.
+ * @return the generated JSON object, should be freed with json_free.
+ *        in the event of an error it will return json_empty_object
  *
  */
 static struct json_object password_change_json(
@@ -639,12 +644,12 @@ failure:
  * Create a JSON object detailing a transaction transaction life cycle events,
  * i.e. begin, commit, roll back
  *
- * @param action a one word description of the event/action
- * @param transaction_id the GUID identifying the current transaction.
- * @param status the status code returned by the operation
- * @param duration the duration of the operation.
+ * @param action[in]         a one word description of the event/action
+ * @param transaction_id[in] the GUID identifying the current transaction.
+ * @param duration[in]       the duration of the operation.
  *
- * @return a JSON object detailing the event
+ * @return the generated JSON object, should be freed with json_free.
+ *        in the event of an error it will return json_empty_object
  */
 static struct json_object transaction_json(
        const char *action,
@@ -717,10 +722,14 @@ failure:
  *
  * Generate a JSON object containing details of a commit failure.
  *
- * @param action the commit action, "commit" or "prepare"
- * @param status the status code returned by commit
- * @param reason any extra failure information/reason available
- * @param transaction_id the GUID identifying the current transaction.
+ * @param action[in]         the commit action, "commit" or "prepare"
+ * @param duration[in]       the duration of the operation.
+ * @param status[in]         the status code returned by commit
+ * @param reason[in]         any extra failure information/reason available
+ * @param transaction_id[in] the GUID identifying the current transaction.
+ *
+ * @return the generated JSON object, should be freed with json_free.
+ *        in the event of an error it will return json_empty_object
  */
 static struct json_object commit_failure_json(
        const char *action,
@@ -805,11 +814,12 @@ failure:
  *
  * Generate a human readable log line detailing a password change.
  *
- * @param mem_ctx The talloc context that will own the generated log line.
- * @param module the ldb module
- * @param request the request
- * @param reply the result/response
- * @param status the status code returned for the underlying ldb operation.
+ * @param[in] mem_ctx           the talloc context that will own the
+ *                              generated log line.
+ * @param[in] module            the ldb module
+ * @param[in] request           the request
+ * @param[in] reply             the result/response
+ * @param[in] auth_info_changed was authentication information changed?
  *
  * @return the generated log line.
  */
@@ -865,11 +875,13 @@ static char *password_change_human_readable(
  * Base64 values are enclosed in {}
  * Truncated values are indicated by three trailing dots "..."
  *
- * @param ldb The ldb_context
- * @param buffer The attributes will be appended to the buffer.
- *               assumed to have been allocated via talloc.
- * @param operation The operation type
- * @param message the message to process
+ * @param[in]  ldb       the ldb_context
+ * @param[out] buffer    the attributes will be appended to the buffer.
+ *                       assumed to have been allocated via talloc.
+ * @param[in]  operation the operation type
+ * @param[in]  message   the message to process
+ *
+ * @return a pointer to buffer
  *
  */
 static char *log_attributes(
@@ -962,10 +974,10 @@ static char *log_attributes(
  *
  * Generate a human readable log entry detailing an ldb operation.
  *
- * @param mem_ctx The talloc context owning the returned string.
- * @param module the ldb module
- * @param request the request
- * @param reply the result of the operation
+ * @param[in] mem_ctx the talloc context owning the returned string.
+ * @param[in] module  the ldb module
+ * @param[in] request the request
+ * @param[in] reply   the result of the operation
  *
  * @return the log entry.
  *
@@ -1041,10 +1053,10 @@ static char *operation_human_readable(
  *
  * Generate a human readable log entry detailing a replicated update operation
  *
- * @param mem_ctx The talloc context owning the returned string.
- * @param module the ldb module
- * @param request the request
- * @param reply the result of the operation.
+ * @param[in] mem_ctx the talloc context owning the returned string.
+ * @param[in] module  the ldb module
+ * @param[in] request the request
+ * @param[in] reply   the result of the operation.
  *
  * @return the log entry.
  *
@@ -1103,9 +1115,9 @@ static char *replicated_update_human_readable(
  * Create a human readable log entry detailing a transaction event.
  * i.e. begin, commit, roll back
  *
- * @param mem_ctx The talloc context owning the returned string.
- * @param action a one word description of the event/action
- * @param duration the duration of the transaction.
+ * @param[in] mem_ctx  the talloc context owning the returned string.
+ * @param[in] action   a one word description of the event/action
+ * @param[in] duration the duration of the transaction.
  *
  * @return the log entry
  */
@@ -1137,10 +1149,11 @@ static char *transaction_human_readable(
  *
  * Generate generate a human readable log entry detailing a commit failure.
  *
- * @param mem_ctx The talloc context owning the returned string.
- * @param action the commit action, "prepare" or "commit"
- * @param status the status code returned by commit
- * @param reason any extra failure information/reason available
+ * @param[in] mem_ctx  the talloc context owning the returned string.
+ * @param[in] action   the commit action, "prepare" or "commit"
+ * @param[in] duration the duration of the transaction.
+ * @param[in] status   the status code returned by commit
+ * @param[in] reason   any extra failure information/reason available
  *
  * @return the log entry
  */
@@ -1177,10 +1190,9 @@ static char *commit_failure_human_readable(
  * Log the details of an ldb operation in JSON and or human readable format
  * and send over the message bus.
  *
- * @param module the ldb_module
- * @param request the operation request.
- * @param reply the operation result.
- * @param the status code returned for the operation.
+ * @param[in] module  the ldb_module
+ * @param[in] request the operation request.
+ * @param[in] reply   the operation result.
  *
  */
 static void log_standard_operation(
@@ -1309,9 +1321,9 @@ static void log_standard_operation(
  * Log the details of a replicated update in JSON and or human readable
  * format and send over the message bus.
  *
- * @param module the ldb_module
+ * @param module  the ldb_module
  * @param request the operation request
- * @param reply the result of the operation.
+ * @param reply   the result of the operation.
  *
  */
 static void log_replicated_operation(
@@ -1366,9 +1378,9 @@ static void log_replicated_operation(
  * Log the details of an ldb operation in JSON and or human readable format
  * and send over the message bus.
  *
- * @param module the ldb_module
- * @param request the operation request
- * @part reply the result of the operation
+ * @param[in] module  the ldb_module
+ * @param[in] request the operation request
+ * @param[in] reply   the result of the operation
  *
  */
 static void log_operation(
@@ -1395,9 +1407,9 @@ static void log_operation(
  * Log the details of a transaction event in JSON and or human readable format
  * and send over the message bus.
  *
- * @param module the ldb_module
- * @param action the transaction event i.e. begin, commit, roll back.
- * @param log_level the logging level
+ * @param[in] module    the ldb_module
+ * @param[in] action    the transaction event i.e. begin, commit, roll back.
+ * @param[in] log_level the logging level
  *
  */
 static void log_transaction(
@@ -1453,9 +1465,9 @@ static void log_transaction(
  * Log the details of a commit failure in JSON and or human readable
  * format and send over the message bus.
  *
- * @param module the ldb_module
- * @param action the commit action "prepare" or "commit"
- * @param status the ldb status code returned by prepare commit.
+ * @param[in] module the ldb_module
+ * @param[in] action the commit action "prepare" or "commit"
+ * @param[in] status the ldb status code returned by prepare commit.
  *
  */
 static void log_commit_failure(
@@ -1531,8 +1543,8 @@ struct audit_callback_context {
  * the operations, a callback needs to be registered to process the results
  * of the LDB operations.
  *
- * @param req the ldb request
- * @param res the result of the operation
+ * @param[in] req the ldb request
+ * @param[in] res the result of the operation
  *
  * @return the LDB_STATUS
  */
@@ -1588,8 +1600,8 @@ static int audit_callback(struct ldb_request *req, struct ldb_reply *ares)
  * Add the current transaction identifier in the module private data,
  * to the request as a control.
  *
- * @param module
- * @param req the request.
+ * @param[in] module the ldb_module
+ * @param[in] req    the request.
  *
  * @return an LDB_STATUS code, LDB_SUCCESS if successful.
  */
@@ -1624,8 +1636,8 @@ static int add_transaction_id(
  *
  * Log the details of an add operation.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1675,8 +1687,8 @@ static int log_add(
  *
  * Log the details of an delete operation.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1725,8 +1737,8 @@ static int log_delete(
  *
  * Log the details of a modify operation.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1777,8 +1789,8 @@ static int log_modify(
  * process a transaction start, as we don't currently log transaction starts
  * just generate the new transaction_id.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1805,8 +1817,8 @@ static int log_start_transaction(struct ldb_module *module)
  * Log the details of a prepare commit, currently only details of
  * failures are logged.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1829,8 +1841,8 @@ static int log_prepare_commit(struct ldb_module *module)
  * process a transaction end, as we don't currently log transaction ends
  * just clear transaction_id.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1863,8 +1875,8 @@ static int log_end_transaction(struct ldb_module *module)
  *
  * Log details of a transaction roll back.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */
@@ -1884,8 +1896,8 @@ static int log_del_transaction(struct ldb_module *module)
  *
  * Log the details of an extended operation.
  *
- * @param module the ldb_module
- * @param req the ldb_request
+ * @param[in] module the ldb_module
+ * @param[in] req    the ldb_request
  *
  * @return ldb status code
  */