From 581477fa70bf28b095e5150e2b53d7640406c603 Mon Sep 17 00:00:00 2001
From: tchernobog <tchernobog@3ecf2c5c-341e-0410-92b4-d18e462d057c>
Date: Sun, 17 Sep 2006 22:07:50 +0000
Subject: [PATCH] - Some more auditing

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1264 3ecf2c5c-341e-0410-92b4-d18e462d057c
---
 .../sgpemv2/cpu_policies_gatekeeper.hh        | 36 ++++++++++++++-----
 src/simulation_controller.hh                  | 26 ++++++++++++++
 2 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/src/backend/sgpemv2/cpu_policies_gatekeeper.hh b/src/backend/sgpemv2/cpu_policies_gatekeeper.hh
index 2343e11..cb5adc4 100644
--- a/src/backend/sgpemv2/cpu_policies_gatekeeper.hh
+++ b/src/backend/sgpemv2/cpu_policies_gatekeeper.hh
@@ -42,11 +42,14 @@ namespace sgpem
 {
   class CPUPoliciesGatekeeper;
 
-  /** \brief FIXME document me
-
-
+  /** \brief This is the container of all CPU policies found on the system.
+   *
+   * Keeps all registered policy managers in order to access to available policies
+   * Every CPUPolicyManager should register itself to this class so that
+   * its policies are made available to the user.
+   *
+   * This class' constructor should be friend with Singleton (shake hands, make a smile!).
    */
-
   class SG_DLLEXPORT CPUPoliciesGatekeeper : public Singleton<CPUPoliciesGatekeeper>
   {
     friend class Singleton<CPUPoliciesGatekeeper>;
@@ -55,26 +58,43 @@ namespace sgpem
     typedef CPUPolicyManager Manager;
     typedef std::vector<Manager*> Managers;
     
+    /** \brief Returns registered ::CPUManager */
     Managers   get_registered() const;
 
+    /** \brief Register a new manager
+     *
+     * A no-op if a manager of the same type already exists
+     */
     void       register_manager(CPUPolicyManager* manager);
 
+    /** \brief Unregister a given manager
+     *
+     * If not present, it is a no-op. When unregistering a manager, care should be taken 
+     * to ensure that the currently active policies weren't managed by it. If so, the policies
+     * should be deactivated before removal.
+     */
     void       unregister_manager(CPUPolicyManager* manager);
 
+    /** \brief Returns the currently active policy
+     *
+     * If no policy was previously activated for the attached 
+     * ::History, throw an appropriate exception.
+     */
     CPUPolicy* get_current_policy(History* history) throw(std::runtime_error);
 
-    /**
-     Associates policy with history. If an exception is thrown, the current associated
-     policy with this history (if there are any), is \b no more active, \b nor associated 
+    /** \brief Associates a policy with history. 
+     * If an exception is thrown, the current associated *policy with this history 
+     * (if there are any), is \b no more active, \b nor associated 
      */
     void       activate_policy(History* history, CPUPolicy* policy) throw(UserInterruptException, MalformedPolicyException);
 
   private:
+
     CPUPoliciesGatekeeper();     //private constructor.
     CPUPoliciesGatekeeper(const CPUPoliciesGatekeeper&);
     CPUPoliciesGatekeeper& operator=(const CPUPoliciesGatekeeper&);
 
-    // Deactivates active policies managed by the specified manager.
+    /** \brief Deactivates active policies managed by the specified manager. */
     void       deactivate_policies(CPUPolicyManager* manager);
 
     Managers                           _registered;
diff --git a/src/simulation_controller.hh b/src/simulation_controller.hh
index b5688d1..aff3b2a 100644
--- a/src/simulation_controller.hh
+++ b/src/simulation_controller.hh
@@ -36,6 +36,7 @@ namespace sgpem
 
 
   /** \brief Helper class for controlling the simulation via callback
+   * from the GUI
    */
   class SimulationController : public SimulationObserver
   {
@@ -43,13 +44,38 @@ namespace sgpem
     SimulationController(Simulation& simulation, Glib::RefPtr<Gnome::Glade::Xml> main_window);
     virtual ~SimulationController();
     
+    /** \brief Update sensitivities of toolbar buttons and menu items 
+     * watching the state of the ::Simulation 
+     */
     void update(const Simulation& simulation);
     
   private:
+
+    /** \brief Called when the "Play" action is requested 
+     *  
+     * Modifies toolbar buttons and menu items sensitivities
+     */
     void on_simulation_run();
+
+    /** \brief Called when the "Pause" action is requested 
+     *  
+     * Modifies toolbar buttons and menu items sensitivities
+     */
     void on_simulation_pause();
+
+    /** \brief Called when the "Stop" action is requested 
+     *  
+     * Modifies toolbar buttons and menu items sensitivities
+     */
     void on_simulation_stop();
 
+    /** \brief Calls Simulation::run() and manage possibly raised exceptions
+     *  
+     * This function is called every Simulation::get_speed() milliseconds by
+     * ::on_simulation_run(), and performs a single step of the simulation.
+     * Manages all exceptions that could be raised by Simulation::run(), displaying
+     * meaningful(?) error messages if shit happens.
+     */
     bool run_simulation_adaptor();
 
     Simulation&      _sim;