objres: document the functions

include/vlc_objects.h

@@ -131,9 +131,77 @@ VLC_API char *vlc_object_get_name( const vlc_object_t * ) VLC_USED;
 #define vlc_object_release(a) \
     vlc_object_release( VLC_OBJECT(a) )
 
-VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *, size_t);
-VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *, size_t, size_t);
-VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *, const char *);
-VLC_API void vlc_obj_free(vlc_object_t *, void *);
+/**
+ * @defgroup objres Object resources
+ *
+ * The object resource functions tie resource allocation to an instance of
+ * a module through a VLC object.
+ * Such resource will be automatically freed, in first in last out order,
+ * when the module instance associated with the VLC object is terminated.
+ *
+ * Specifically, if the module instance activation/probe function fails, the
+ * resource will be freed immediately after the failure within
+ * vlc_module_load(). If the activation succeeds, the resource will be freed
+ * when the module instance is terminated with vlc_module_unload().
+ *
+ * This is a convenience mechanism to save explicit clean-up function calls
+ * in modules.
+ *
+ * @{
+ */
+
+/**
+ * Allocates memory for a module.
+ *
+ * This function allocates memory from the heap for a module instance.
+ * The memory is uninitialized.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param size byte size of the memory allocation
+ *
+ * @return a pointer to the allocated memory, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
 
+/**
+ * Allocates a zero-initialized table for a module.
+ *
+ * This function allocates a table from the heap for a module instance.
+ * The memory is initialized to all zeroes.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param nmemb number of table entries
+ * @param size byte size of a table entry
+ *
+ * @return a pointer to the allocated memory, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
+                                        size_t size);
+
+/**
+ * Duplicates a string for a module.
+ *
+ * This function allocates a copy of a nul-terminated string for a module
+ * instance.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param str string to copy
+ *
+ * @return a pointer to the copy, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);
+
+/**
+ * Manually frees module memory.
+ *
+ * This function manually frees a resource allocated with vlc_obj_malloc(),
+ * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
+ * terminated. This is seldom necessary.
+ *
+ * @param obj VLC object that the allocation was tied to
+ * @param ptr pointer to the allocated resource
+ */
+VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);
+
+/** @} */
 /** @} */