From c75acecc3035af732936c92e67c29e0937a32178 Mon Sep 17 00:00:00 2001
From: David Sommerseth <dazo@users.sourceforge.net>
Date: Mon, 4 Mar 2013 10:21:09 +0100
Subject: auth plug-in: Improved documentation for auth plug-ins

Signed-off-by: David Sommerseth <dazo@users.sourceforge.net>
---
 auth/eurephia_authplugin_driver.h | 41 ++++++++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 9 deletions(-)

(limited to 'auth/eurephia_authplugin_driver.h')

diff --git a/auth/eurephia_authplugin_driver.h b/auth/eurephia_authplugin_driver.h
index eae4513..69b8f7e 100644
--- a/auth/eurephia_authplugin_driver.h
+++ b/auth/eurephia_authplugin_driver.h
@@ -28,27 +28,50 @@
 #ifndef EUREPHIA_AUTHPLUGIN_DRIVER_H_
 #define EUREPHIA_AUTHPLUGIN_DRIVER_H_
 
-typedef enum { eptAUTH } ePluginType;
+/**
+ *  Supported plug-in types
+ */
+typedef enum {
+        eptAUTH  /**< Used by authentication plug-ins */
+} ePluginType;
+
+/**
+ *   Translation table for ePluginType into a readable string
+ *   This table must match the ePluginType enumeration.
+ */
 static const char *___ePluginTypeString[] = {
-        "authentication",
+        "authentication",  /* eptAUTH */
         NULL
 };
 
 
+/**
+ *  Struct providing plug-in information
+ */
 typedef const struct __ePluginInfo {
-        const char *name;
-        const char *version;
-        const char *copyright;
-        const ePluginType pluginType;
-        const int APIversion;
+        const char *name;             /**< Readable plug-in name */
+        const char *version;          /**< Plug-in version string */
+        const char *copyright;        /**< Copyright of the plug-in */
+        const ePluginType pluginType; /**< Plug-in type */
+        const int APIversion;         /**< Plug-in API level support */
 } ePluginInfo;
 
+
+/**
+ *  Simple function for getting a readable string of the plug-in type.
+ *
+ *  @return Returns a char pointer to a static const buffer containing the
+ *          plug-in type.
+ */
 static inline const char * ePluginTypeString(ePluginInfo *plginf)
 {
         return ___ePluginTypeString[plginf->pluginType];
 }
 
 
+/**
+ *  Authentication result codes
+ */
 typedef enum { eAUTH_FAILED,     /**< Authentication failed */
                eAUTH_SUCCESS,    /**< Authentication successful */
                eAUTH_PLGERROR    /**< An error occured in the auth plug-in */
@@ -58,8 +81,8 @@ typedef enum { eAUTH_FAILED,     /**< Authentication failed */
  *  Result type for authentication plug-ins
  */
 typedef struct __eAuthResult {
-        eAuthResStatus status;
-        char *msg;
+        eAuthResStatus status;   /**< Overall status of the operation */
+        char *msg;               /**< Optinal descriptive information */
 } eAuthResult;
 
 
-- 
cgit