From 78fbedf3695761d9966d3dea6c1fe5adb8b18196 Mon Sep 17 00:00:00 2001
From: Andreas Schneider <asn@samba.org>
Date: Mon, 3 May 2010 21:04:54 +0200
Subject: tevent: Document missing callback typedefs.

---
 lib/tevent/tevent.h | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

(limited to 'lib/tevent')

diff --git a/lib/tevent/tevent.h b/lib/tevent/tevent.h
index e928a99407..8046bbc028 100644
--- a/lib/tevent/tevent.h
+++ b/lib/tevent/tevent.h
@@ -630,7 +630,34 @@ void *_tevent_req_data(struct tevent_req *req);
 	talloc_get_type_abort(_tevent_req_data(_req), _type)
 #endif
 
-typedef char *(*tevent_req_print_fn)(struct tevent_req *, TALLOC_CTX *);
+/**
+ * @brief The print function which can be set for a tevent async request.
+ *
+ * @param[in]  req      The tevent async request.
+ *
+ * @param[in]  ctx      A talloc memory context which can be uses to allocate
+ *                      memory.
+ *
+ * @return              An allocated string buffer to print.
+ *
+ * Example:
+ * @code
+ *   static char *my_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
+ *   {
+ *     struct my_data *data = tevent_req_data(req, struct my_data);
+ *     char *result;
+ *
+ *     result = tevent_req_default_print(mem_ctx, req);
+ *     if (result == NULL) {
+ *       return NULL;
+ *     }
+ *
+ *     return talloc_asprintf_append_buffer(result, "foo=%d, bar=%d",
+ *       data->foo, data->bar);
+ *   }
+ * @endcode
+ */
+typedef char *(*tevent_req_print_fn)(struct tevent_req *req, TALLOC_CTX *ctx);
 
 /**
  * @brief This function sets a print function for the given request.
@@ -676,7 +703,14 @@ char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
  */
 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
 
-typedef bool (*tevent_req_cancel_fn)(struct tevent_req *);
+/**
+ * @brief A typedef for a cancel function for a tevent request.
+ *
+ * @param[in]  req      The tevent request calling this function.
+ *
+ * @return              True if the request could be canceled, false if not.
+ */
+typedef bool (*tevent_req_cancel_fn)(struct tevent_req *req);
 
 /**
  * @brief This function sets a cancel function for the given tevent request.
-- 
cgit