Add doc to include/libcgroup/error.h

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

diff --git a/include/libcgroup/error.h b/include/libcgroup/error.h
index b725c18339e79cd528a16cabec85c7656f21979b..9f91479351579f5082ebb2e2ddb12d8176c97b8d 100644 (file)
--- a/include/libcgroup/error.h
+++ b/include/libcgroup/error.h
@@ -9,6 +9,21 @@
 
 __BEGIN_DECLS
 
+/**
+ * @defgroup group_errors 6. Error handling
+ * @{
+ *
+ * @name Error handling
+ * @{
+ * Unless states otherwise in documentation of a function, all functions
+ * return @c int, which is zero (0) when the function succeeds, and positive
+ * number if the function fails.
+ *
+ * The returned integer is one of the ECG* values described below. Value
+ * #ECGOTHER means that the error was caused by underlying OS and the real
+ * cause can be found by calling cgroup_get_last_errno().
+ */
+
 enum {
        ECGROUPNOTCOMPILED = 50000,
        ECGROUPNOTMOUNTED,
@@ -16,8 +31,10 @@ enum {
        ECGROUPNOTCREATED,
        ECGROUPSUBSYSNOTMOUNTED,
        ECGROUPNOTOWNER,
-       ECGROUPMULTIMOUNTED,/* Controllers bound to different mount points */
-       ECGROUPNOTALLOWED,  /* This is the stock error. Default error. */
+       /** Controllers bound to different mount points */
+       ECGROUPMULTIMOUNTED,
+       /* This is the stock error. Default error. @todo really? */
+       ECGROUPNOTALLOWED,
        ECGMAXVALUESEXCEEDED,
        ECGCONTROLLEREXISTS,
        ECGVALUEEXISTS,
@@ -26,29 +43,49 @@ enum {
        ECGFAIL,
        ECGROUPNOTINITIALIZED,
        ECGROUPVALUENOTEXIST,
-       /* Represents error coming from other libraries like glibc. libcgroup
-        * users need to check errno upon encoutering ECGOTHER.
+       /**
+        * Represents error coming from other libraries like glibc. @c libcgroup
+        * users need to check cgroup_get_last_errno() upon encountering this
+        * error.
         */
-       ECGOTHER,       /* OS error, see errno */
+       ECGOTHER,
        ECGROUPNOTEQUAL,
        ECGCONTROLLERNOTEQUAL,
-       ECGROUPPARSEFAIL, /* Failed to parse rules configuration file. */
-       ECGROUPNORULES, /* Rules list does not exist. */
+       /** Failed to parse rules configuration file. */
+       ECGROUPPARSEFAIL,
+       /** Rules list does not exist. */
+       ECGROUPNORULES,
        ECGMOUNTFAIL,
-       ECGSENTINEL,    /* Please insert further error codes above this */
-       ECGEOF,         /* End of file, iterator */
-       ECGCONFIGPARSEFAIL,/* Failed to parse config file (cgconfig.conf). */
+       /**
+        * Not an real error, just a auxiliary mark in the enum.
+        * Please insert further error codes above this.
+        */
+       ECGSENTINEL,
+       /**
+        * Not an real error, it just indicates that iterator has come to end
+        * of sequence and no more items are left.
+        */
+       ECGEOF,
+       /** Failed to parse config file (cgconfig.conf). */
+       ECGCONFIGPARSEFAIL,
        ECGNAMESPACEPATHS,
        ECGNAMESPACECONTROLLER,
        ECGMOUNTNAMESPACE,
 };
 
+/**
+ * Legacy definition of ECGRULESPARSEFAIL error code.
+ */
 #define ECGRULESPARSEFAIL      ECGROUPPARSEFAIL
 
 /**
- * Return error corresponding to @code in human readable format.
- * @code: error code for which the corresponding error string is to be
- * returned
+ * Format error code to a human-readable English string. No internationalization
+ * is currently done. Returned pointer leads to @c libcgroup memory and
+ * must not be freed nor modified. The memory is rewritten by subsequent
+ * call to this function.
+ * @param code Error code for which the corresponding error string is
+ * returned. When #ECGOTHER is used, text with glibc's description of
+ * cgroup_get_last_errno() value is returned.
  */
 const char *cgroup_strerror(int code);
 
@@ -57,6 +94,10 @@ const char *cgroup_strerror(int code);
  */
 int cgroup_get_last_errno(void);
 
+/**
+ * @}
+ * @}
+ */
 __END_DECLS
 
 #endif /* _LIBCGROUP_INIT_H */