X-Git-Url: http://git.liburcu.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fhandle.h;fp=include%2Flttng%2Fhandle.h;h=08f9eaad965be23569ac500acfb6dd4206237551;hp=14a0e54072a0fb570a7c61ad5cd1f01a056f5c14;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b

diff --git a/include/lttng/handle.h b/include/lttng/handle.h
index 14a0e5407..08f9eaad9 100644
--- a/include/lttng/handle.h
+++ b/include/lttng/handle.h
@@ -15,42 +15,100 @@
 extern "C" {
 #endif
 
+/*!
+@addtogroup api_session
+@{
+*/
+
 /*
  * Handle used as a context for commands.
  *
  * The structures should be initialized to zero before use.
  */
 #define LTTNG_HANDLE_PADDING1 16
+
+/*!
+@brief
+    Recording session handle.
+
+Such a structure is a pair of a \ref api_session "recording session"
+name and a \ref api-channel-domain "tracing domain" summary.
+
+Some functions which accept a recording session handle parameter ignore
+the recording session name or the tracing domain summary.
+
+Create a recording session handle with lttng_create_handle().
+
+Destroy a recording session handle with lttng_destroy_handle().
+*/
 struct lttng_handle {
+	/// \ref api_session "Recording session" name.
 	char session_name[LTTNG_NAME_MAX];
+
+	/// \ref api-channel-domain "Tracing domain" summary.
 	struct lttng_domain domain;
 
 	char padding[LTTNG_HANDLE_PADDING1];
 };
 
-/*
- * Create an handle used as a context for every request made to the library.
- *
- * This handle contains the session name and domain on which the command will
- * be executed. A domain is basically a tracer like the kernel or user space.
- *
- * A NULL domain indicates that the handle is not bound to a specific domain.
- * This is mostly used for actions that apply on a session and not on a domain
- * (e.g lttng_set_consumer_url).
- *
- * Return a newly allocated handle that should be freed using
- * lttng_destroy_handle. On error, NULL is returned.
- */
+/*!
+@brief
+    Creates and returns a recording session handle from the
+    \ref api_session "recording session" name
+    \lt_p{session_name} and the optional
+    \ref api-channel-domain "tracing domain" summary \lt_p{domain}.
+
+@param[in] session_name
+    @parblock
+    Recording session name part of the recording session handle to
+    create.
+
+    May be \c NULL.
+    @endparblock
+@param[in] domain
+    @parblock
+    Tracing domain summary part of the recording session handle to
+    create.
+
+    May be \c NULL.
+    @endparblock
+
+@returns
+    @parblock
+    New recording session handle.
+
+    Destroy the returned handle with lttng_destroy_handle().
+    @endparblock
+
+@sa lttng_destroy_handle() --
+    Destroys a recording session handle.
+*/
 LTTNG_EXPORT extern struct lttng_handle *lttng_create_handle(const char *session_name,
 							     struct lttng_domain *domain);
 
-/*
- * Destroy an handle that has been previously created with lttng_create_handle.
- *
- * It free the given pointer making it unusable.
- */
+/*!
+@brief
+    Destroys the recording session handle \lt_p{handle}.
+
+@note
+    @parblock
+    This function doesn't destroy the recording session named
+    \lt_p{handle->session_name}, but only the handle itself.
+
+    Use lttng_destroy_session_ext() to destroy a recording session.
+    @endparblock
+
+@param[in] handle
+    @parblock
+    Recording session handle to destroy.
+
+    May be \c NULL.
+    @endparblock
+*/
 LTTNG_EXPORT extern void lttng_destroy_handle(struct lttng_handle *handle);
 
+/// @}
+
 #ifdef __cplusplus
 }
 #endif