-/*
- * BT_PUT: calls bt_put() with a variable, then sets this variable to NULL.
- *
- * A common action with Babeltrace objects is to create or get one, perform
- * an action with it, and then put it. To avoid putting it a second time
- * later (if an error occurs, for example), the variable is often reset
- * to NULL after putting the object it points to. Since this is so
- * common, the BT_PUT() macro can be used to do just that.
- *
- * It is safe to call this function with a variable containing NULL.
- *
- * @param obj Variable pointing to a Babeltrace object.
- */
-#define BT_PUT(_obj) \
+/**
+@defgroup refs Reference counting management
+@ingroup apiref
+@brief Common reference counting management for all Babeltrace objects.
+
+The macros and functions of this module are everything that is needed
+to handle the <strong><em>reference counting</em></strong> of
+Babeltrace objects.
+
+All Babeltrace objects can be shared by multiple owners thanks to
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counting</a>. A function which returns a Babeltrace object owned
+by another one increments its reference count so that the caller
+becomes an owner too.
+
+When a Babeltrace object is created, its reference count is initialized
+to 1. It is your responsibility to discard the object when you don't
+need it anymore with bt_put().
+
+The two macros BT_PUT() and BT_MOVE() operate on \em variables rather
+than pointer values. You should use BT_PUT() instead of bt_put() when
+possible to avoid "double puts". For the same reason, you should use use
+BT_MOVE() instead of performing manual reference moves between
+variables.
+
+@file
+@brief Reference counting management macros and functions.
+@sa refs
+
+@addtogroup refs
+@{
+*/
+
+/**
+@brief Calls bt_put() on variable \p _var, then sets \p _var to \c NULL.
+
+Using this macro is considered safer than calling bt_put() because it
+makes sure that the variable which used to contain a reference to a
+Babeltrace object is set to \c NULL so that a future BT_PUT() or
+bt_put() call will not cause another, unwanted reference decrementation.
+
+@param[in,out] _var Variable containing a Babeltrace object's
+ address (can be \c NULL).
+
+@post <strong>If \c _var is not \c NULL</strong>, its reference
+ count is decremented.
+@post \p _var is \c NULL.
+
+@sa BT_MOVE(): Transfers the ownership of a Babeltrace object from a
+ variable to another.
+*/
+#define BT_PUT(_var) \