docs: Partially document the liblttng-ctl C API

[lttng-tools.git] / include / lttng / handle.h

diff --git a/include/lttng/handle.h b/include/lttng/handle.h
index 14a0e54072a0fb570a7c61ad5cd1f01a056f5c14..08f9eaad965be23569ac500acfb6dd4206237551 100644 (file)
--- 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