Documentation fixes and code cleanup

1 files changed, 137 insertions, 61 deletions

diff --git a/src/input/inputEventHandler.h b/src/input/inputEventHandler.h
index a2e943e..783640f 100644
--- a/src/input/inputEventHandler.h
+++ b/src/input/inputEventHandler.h
@@ -26,11 +26,10 @@
 #include "detail/policyChain.h"
 #include "detail/systemTraits.h"
 
-/////////////////////////////////////////////////////////////////////////
-// InputEventContext:
-//  For handling access control, this specifies who sent the input event.
-//  This only makes sense in the privileged input handler chain.
-/////////////////////////////////////////////////////////////////////////
+/**
+ * For handling access control, this specifies who sent the input event.
+ * This only really makes sense in the privileged input handler chain.
+ */
 struct InputEventContext
 {
 	InputEventContext()
@@ -38,11 +37,11 @@ struct InputEventContext
 		hasBeenDenied = false;
 	}
 
-	virtual pid_t senderPid() const = 0;
-	virtual uid_t senderUid() const = 0;
-	virtual gid_t senderGid() const = 0;
+	virtual pid_t senderPid() const = 0; /**< PID of the sending process */
+	virtual uid_t senderUid() const = 0; /**< UID of the sending process */
+	virtual gid_t senderGid() const = 0; /**< GID of the sending process */
 
-	// Support the generation of meaningful log messages:
+	/** Support the generation of meaningful log messages. */
 	mutable bool hasBeenDenied;
 };
 
@@ -61,15 +60,21 @@ namespace input_policy
 //  Policies are tied together using the detail::PolicyChain class.
 /////////////////////////////////////////////////////////////////////////
 
-/////////////////////////////////////////////////////////////////////////
-// Security Policy:
-//  At the moment there are two security policies:
-//  1. If the user is on a local seat, allow. If the user is privileged,
-//     allow. Else deny.
-//  2. Allow everybody.
-//  Additional security policies can be added by following the example
-//  set by AllowLocalOrPrivileged
-/////////////////////////////////////////////////////////////////////////
+/**
+ * Security Policy.
+ * At the moment there are two security policies:
+ * -* If the user is on a local seat, allow. If the user is privileged,
+ *    allow. Else deny.
+ * -* Allow everybody.
+ *
+ * Additional security policies can be added by following the example
+ * set by \ref AllowLocalOrPrivileged
+ *
+ * \param PolicyImpl The implementation class that security decisions
+ *   should be delegated to.
+ * \see {AllowLocalOrPrivileged}
+ * \see {AllowEverybody}
+ */
 template<typename PolicyImpl>
 BEGIN_POLICY_CLASS(Security)
 {
@@ -80,25 +85,43 @@ BEGIN_POLICY_CLASS(Security)
 }
 END_POLICY_CLASS
 
+/**
+ * Check the default security model.
+ */
 struct AllowLocalOrPrivileged
 {
 	static bool allow(InputEventContext const*);
 };
 
+/**
+ * Do not restrict execution.
+ */
 struct AllowEverybody
 {
 	static bool allow(InputEventContext const*);
 };
 
+/**
+ * Shorthand for unrestricted execution.
+ */
 typedef Security<AllowEverybody> Unprivileged;
 
-/////////////////////////////////////////////////////////////////////////
-// System Requirements:
-//  At the moment, this is trivial, as PVS only runs on Linux. But,
-//  as porting efforts are already underway, we include the necessary
-//  machinery anyway.
-/////////////////////////////////////////////////////////////////////////
+/**
+ * System Requirements.
+ *
+ * At the moment, this is trivial, as PVS only runs on Linux. But,
+ * as porting efforts are already underway, we include the necessary
+ * machinery anyway.
+ *
+ * \param Trait... a list of system traits that need to be
+ *   present in order for the handler that this policy is applied to
+ *   to run.
+ */
+#ifdef DOXYGEN_RUNNING
+template<typename Trait...>
+#else
 template<IMPLICIT_TYPE_LIST_PARAMS(Trait)>
+#endif
 BEGIN_POLICY_CLASS(Require)
 {
 	static const bool areSystemRequirementsFulfilled =
@@ -109,19 +132,27 @@ BEGIN_POLICY_CLASS(Require)
 }
 END_POLICY_CLASS
 
-/////////////////////////////////////////////////////////////////////////
-// System Requirements:
-//  At the moment, this is trivial, as PVS only runs on Linux. But,
-//  as porting efforts are already underway, we include the necessary
-//  machinery anyway.
-/////////////////////////////////////////////////////////////////////////
+#ifndef DOXYGEN_RUNNING
 enum {
 	HANDLER_CODE_DONT_CARE = 0xffff,
 	HANDLER_VALUE_DONT_CARE = 0xffffffff
 };
-
-struct T;
-
+#endif
+
+/**
+ * Event selection.
+ *
+ * This policy makes the handler it is applied to applicable if the
+ * template parameters \c EventType, \c EventCode and \c EventValue
+ * match the corresponding fields of the incoming \ref InputEvent.
+ *
+ * Can be applied multiple times, and will be combined by logical
+ * OR.
+ *
+ * \param EventType Match the \ref InputEvent::type() field.
+ * \param EventCode (optional:) Match the \ref InputEvent::code() field.
+ * \param EventValue (optional:) Match the \ref InputEvent::value() field.
+ */
 template<unsigned short EventType,
 		unsigned short EventCode = HANDLER_CODE_DONT_CARE,
 		unsigned int EventValue = HANDLER_VALUE_DONT_CARE>
@@ -140,6 +171,7 @@ BEGIN_POLICY_CLASS(Match)
 };
 END_POLICY_CLASS
 
+#ifndef DOXYGEN_RUNNING
 namespace detail
 {
 
@@ -177,46 +209,71 @@ struct InputEventHandlerPolicyBase
 	}
 };
 
-}
+} // namespace detail
+#endif // DOXYGEN_RUNNING
+
 }
 
-/////////////////////////////////////////////////////////////////////////
-// We want a nice non-generic base so we can make a list of polymorphic
-// handlers.
-//
-// The actual handler class need to provide doHandle and can override
-// allow and isApplicable.
-/////////////////////////////////////////////////////////////////////////
+/**
+ * Base class without template parameters to enable making a list of
+ * polymorphic event handlers.
+ *
+ * The actual handler class needs to provide \ref doHandle and can
+ * override \ref allow and \ref isApplicable.
+ *
+ * \note Do not derive from InputEventHandlerBase to implement
+ *   new event handlers! Derive from InputEventHandler instead.
+ */
 class InputEventHandlerBase
 {
 public:
 	enum HandlerStatus
 	{
-		HANDLER_MATCHED,
-		HANDLER_NOT_ALLOWED,
-		HANDLER_NOT_APPLICABLE
+		HANDLER_MATCHED,		/**< The handler matched the input event and was executed. */
+		HANDLER_NOT_ALLOWED,	/**< Execution of the handler was prevented by security policy. */
+		HANDLER_NOT_APPLICABLE	/**< The handler did not match the input event. */
 	};
 
 	virtual void initialize() = 0;
 	HandlerStatus handle(InputEvent const& evt, InputEventContext const* context = 0);
 
 protected:
+	/**
+	 * Check security preconditions for the execution of this handler.
+	 * This is normally handled by the \ref input_policy::Security policy.
+	 */
 	virtual bool allow(InputEvent const& event, InputEventContext const* context = 0) = 0;
+
+	/**
+	 * Check if this handler can handle the incoming input event.
+	 * This is normally handled by the \ref input_policy::Match policy.
+	 */
 	virtual bool isApplicable(InputEvent const& event, InputEventContext const* context = 0) = 0;
+
+	/**
+	 * Actually handle the incoming event.
+	 * It is assumed that all preconditions have been checked and the handler
+	 * has been initialized at the point where this method is called.
+	 */
 	virtual void doHandle(InputEvent const& event, InputEventContext const* context = 0) = 0;
 };
 
-/////////////////////////////////////////////////////////////////////////
-// Now that the machinery is in place, we can finally define what it
-// is like to be an input event handler:
-/////////////////////////////////////////////////////////////////////////
+/**
+ * Base class for input event handlers.
+ */
+#ifdef DOXYGEN_RUNNING
+template<typename Policy...>
+#else
 template<POLICY_PARAMS>
+#endif
 class InputEventHandler : public InputEventHandlerBase
 {
+#ifndef DOXYGEN_RUNNING
 protected:
 	// instantiate our policy:
 	typedef USE_POLICY(input_policy::detail::InputEventHandlerPolicyBase) policy_type;
 	policy_type policy;
+#endif
 
 public:
 	void initialize()
@@ -224,16 +281,11 @@ public:
 		policy.initialize();
 	}
 
-	// Export this so the handler chain can decide whether to include this handler
+	/** Export this so the handler chain can decide whether to include this handler */
 	static const bool areSystemRequirementsFulfilled = policy_type::areSystemRequirementsFulfilled;
 
 protected:
 
-	typedef InputEventHandler super;
-
-	// allow and isApplicable are actually provided by Policy. If the
-	// handler class wishes to override any of them, the policy implementation
-	// can be called by means of super.
 	bool allow(InputEvent const&, InputEventContext const* context = 0)
 	{
 		return policy.allow(context);
@@ -245,14 +297,19 @@ protected:
 	}
 };
 
-/////////////////////////////////////////////////////////////////////////
-// And we can chain input handlers together:
-/////////////////////////////////////////////////////////////////////////
+/**
+ * Chain \ref InputEventHandler instances together.
+ * The chain is also responsible for the creation of instances.
+ *
+ * \see privilegedInputEventHandlerChain.cpp
+ * \see unprivilegedInputEventHandlerChain.cpp
+ */
 class InputEventHandlerChain
 {
 private:
 	QList<InputEventHandlerBase*> handlers;
 
+#ifndef DOXYGEN_RUNNING // Implementation detail
 	/////////////////////////////////////////////////////////////////////////
 	// We need to statically dispatch on a static member of HandlerType.
 	// Unfortunately, we cannot specialize member functions of a template.
@@ -280,18 +337,31 @@ private:
 		{
 		}
 	};
+#endif // DOXYGEN_RUNNING
 
 public:
-	// Add an event handler to the chain. The argument is only for
-	// compilers which cannot handle template member functions
-	// correctly.
+	/**
+	 * Add an event handler to the chain.
+	 *
+	 * \param fake_parameter The parameter is only for
+	 *   compilers which cannot handle template member functions
+	 *   correctly.
+	 * \return A reference to the receiver, for invocation chaining.
+	 *
+	 * \note Do not pass a value to this function. The function
+	 *   handles creation of an instance itself.
+	 */
 	template<typename HandlerType>
-	InputEventHandlerChain& add(HandlerType const* = 0)
+	InputEventHandlerChain& add(HandlerType const* fake_parameter = 0)
 	{
 		ConditionallyAppend<HandlerType::areSystemRequirementsFulfilled, HandlerType>::doIt(this);
 		return *this;
 	}
 
+	/**
+	 * Call \ref InputEventHandlerBase::initialize() on all
+	 * handlers in the chain.
+	 */
 	void initialize()
 	{
 		QListIterator<InputEventHandlerBase*> i(handlers);
@@ -301,6 +371,12 @@ public:
 		}
 	}
 
+	/**
+	 * Handle an input event. All handlers in the chain are tried
+	 * in the order they were added, until one handler's
+	 * implementation of InputEventHandlerBase::handle() returns
+	 * InputEventHandlerBase::HANDLER_MATCHED.
+	 */
 	void handle(InputEvent const& event, InputEventContext const* context = 0)
 	{
 		QListIterator<InputEventHandlerBase*> i(handlers);