Add documentation to include/libcgroup/init.h

Signed-off-by: Jan Safranek <jsafrane@redhat.com>

1 files changed, 35 insertions, 6 deletions

diff --git a/include/libcgroup/init.h b/include/libcgroup/init.h
index d0e93b4..41eafcc 100644
--- a/include/libcgroup/init.h
+++ b/include/libcgroup/init.h
@@ -9,17 +9,46 @@
 
 __BEGIN_DECLS
 
-/* Functions and structures that can be used by the application*/
+/**
+ * @defgroup group_init 1. Initialization
+ * @{
+ *
+ * @name Initialization
+ * @{
+ * Application must initialize @c libcgroup using cgroup_init() before any
+ * other @c libcgroup function can be called. @c libcgroup caches information
+ * about mounted hierarchies (just what's mounted where, not the control groups
+ * themselves) at this time. There is currently no way to refresh this cache,
+ * i.e. all subsequent mounts/remounts/unmounts are not reflected in this cache
+ * and @c libcgroup may produce unexpected results.
+ *
+ * In addition, there is no way how to clean the cache on application exit.
+ *
+ * @todo this is very bad... There should be at least way how to refresh the
+ * cache and/or an option to refresh it automatically (does kernel provide
+ * any indication, when a filesystem is mounted/unmounted?). Dtto the cleanup
+ * on exit.
+ */
+
+/**
+ * Initialize libcgroup. Information about mounted hierarchies are examined
+ * and cached internally (just what's mounted where, not the groups themselves).
+ */
 int cgroup_init(void);
 
-/*
- * Reads the mount to table to give the mount point of a controller
- * @controller: Name of the controller
- * @mount_point: The string where the mount point is stored. Please note,
- * the caller must free mount_point.
+/**
+ * Returns path where is mounted given controller. Applications should rely on
+ * @c libcgroup API and not call this function directly.
+ * @param controller Name of the controller
+ * @param mount_point The string where the mount point location is stored.
+ * 	Please note, the caller must free the mount_point.
  */
 int cgroup_get_subsys_mount_point(const char *controller, char **mount_point);
 
+/**
+ * @}
+ * @}
+ */
 __END_DECLS
 
 #endif /* _LIBCGROUP_INIT_H */