Documentation fixes and code cleanup

1 files changed, 55 insertions, 10 deletions

diff --git a/src/input/pvsCheckPrivileges.h b/src/input/pvsCheckPrivileges.h
index 92c68fe..37c4c04 100644
--- a/src/input/pvsCheckPrivileges.h
+++ b/src/input/pvsCheckPrivileges.h
@@ -26,6 +26,9 @@
 #include <QHash>
 #include "inputEventHandler.h"
 
+/**
+ * Store the information in an InputEventContext as a plain old datatype.
+ */
 struct CachedInputContext
 {
 	CachedInputContext(InputEventContext const* source)
@@ -69,16 +72,37 @@ uint qHash(CachedInputContext const& p);
 
 class QFileSystemWatcher;
 
+/**
+ * Check user privileges and handle communications with ConsoleKit and PolicyKit.
+ * This is a singleton class.
+ */
 class PVSCheckPrivileges : public QObject
 {
 	Q_OBJECT
 public:
+	/**
+	 * SessionKind distinguishes between local and remote users.
+	 */
 	typedef enum {
-		SESSION_LOCAL,
-		SESSION_NONLOCAL,
-		SESSION_LOOKUP_FAILURE,
-		SESSION_UNKNOWN
+		SESSION_LOCAL,				/**< User is local */
+		SESSION_NONLOCAL,			/**< User is remote */
+		SESSION_LOOKUP_FAILURE,		/**< Failure to look up whether the user is local or remote */
+		SESSION_UNKNOWN				/**< User session kind not (yet) known */
 	} SessionKind;
+
+	/**
+	 * UserPrivilege distinguishes between privileged and unprivileged users.
+	 */
+	typedef enum {
+		USER_PRIVILEGED,			/**< User is privileged */
+		USER_UNPRIVILEGED,			/**< User is unprivileged */
+		USER_LOOKUP_FAILURE,		/**< Failure to look up whether the user is privileged or unprivileged */
+		USER_UNKNOWN				/**< User privilege level not (yet) known */
+	} UserPrivilege;
+
+	/** \name Conversion Functions */
+	/* @{ */
+
 	static QString toString(SessionKind k)
 	{
 		switch(k)
@@ -91,12 +115,6 @@ public:
 		}
 	}
 
-	typedef enum {
-		USER_PRIVILEGED,
-		USER_UNPRIVILEGED,
-		USER_LOOKUP_FAILURE,
-		USER_UNKNOWN
-	} UserPrivilege;
 	static QString toString(UserPrivilege k)
 	{
 		switch(k)
@@ -109,13 +127,40 @@ public:
 		}
 	}
 
+	/* @} */
+
+	/** \name Singleton pattern */
+	/* @{ */
+
+	/** Retrieve the singleton instance. */
 	static PVSCheckPrivileges* instance();
+
+	/** Delete the singleton instance. */
 	static void deleteInstance();
 
+	/* @} */
+
+	/** \name Privilege Checks */
+	/* @{ */
+
+	/** Check for a minimum SessionKind level. \return true if the requirement is fulfilled. */
 	bool require(SessionKind sessionKind, CachedInputContext const& sender);
+
+	/** Check for a minimum UserPrivilege level. \return true if the requirement is fulfilled. */
 	bool require(UserPrivilege userPrivilege, CachedInputContext const& sender);
+
+	/** Check for a minimum SessionKind and UserPrivilege level. \return true if both requirements are fulfilled. */
 	bool require(SessionKind sessionKind, UserPrivilege userPrivilege, CachedInputContext const& sender);
+
+	/* @} */
+
+	/** \name Session Information */
+	/* @{ */
+
+	/** Retrieve the name of the user's X session, according to ConsoleKit. */
 	QString getX11SessionName(CachedInputContext const& sender);
+
+	/** Retrieve the TTY device of the user's X session, according to ConsoleKit. */
 	QString getX11DisplayDevice(CachedInputContext const& sender);
 
 public slots: