- Commented file

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@404 3ecf2c5c-341e-0410-92b4-d18e462d057c

src/simulation.hh

@@ -34,9 +34,26 @@ namespace sgpem
 {
   class Simulation;
 
-  /** 
+  /**
+    \brief Manages a single simulation instance.
+
+    Starting from a base state, simulates the progress of a scheduling system.
+    Given the discrete nature of the implementation, once a scheduling algorithm
+    and its parameters are fixed, the state of the system is a function of time.
+    This doesn't mean the behaviour of the policy is assumed to be deterministic,
+    since this will restrict the range of available policies (we won't be able 
+    to uselottery scheduling, for example).
+
+    It provides methods to edit the state of the simulation, to check the 
+    characteristics of the simulation (advancement speed, advancement mode) and to
+    check which schedulng algorithm is currently in use.
+
+    \remarks Implements the Observer pattern: observes classes \ref History, \ref Scheduler,
+    \ref Policy.
+    \remarks Implements the Controller pattern: ensures Low Coupling between the Frontend and
+    the Backend layers.
+   */
   
-	*/	
 	class SG_DLLEXPORT Simulation : public Observer
 	{
 	public:
@@ -49,19 +66,85 @@ namespace sgpem
 		
 		Simulation();
 		
+	  	/**
+		  \brief Runs the simulation.
+		  Advances the simulation by one or more steps, depending on the
+		  actual state and on the value set with set_mode().
+		 */  
 		void 	run();
+
+		/**
+		  \brief Pauses a running simulation.
+		  It is obviously useful only when the advancement mode is continue.
+		  Calling again run() will cause the simulation to start from the current
+		  simulation step.
+		 */
 		void 	pause();
+
+		/**
+		  \brief Stops the simulation.
+		  Behaves in the same way as pause(), except that the next call to run() 
+		  will cause the simulation to start from the beginning.
+		 */
 		void 	stop();
+
+		/**
+		  \brief Reset the simulation.
+		  Erases the state of the simulation, and takes care of removing any 
+		  residual or temporary data to ensure the simulation has reached a 
+		  clean and stable state.
+		 */
 		void 	reset();
+
+		/**
+		  \brief Causes the simulation to jump to the given time unit.
+		 */
 		void	jump_to(const uint&);
-				
+		
+		/**		  
+		  \brief Setter for the attribute timer_interval. 
+		  This method is used to define how a single time unit is to be 
+		  interpreted when the simulation advancement mode is continue.
+		  The input value is in milliseconds, and it must be in range [0, 10000].
+		 */
 		void 	set_timer(const int&);
-		int		get_timer() const;
+		
+		/**
+		  \see set_timer()
+		 */
+		int	get_timer() const;
+		
+		/**
+		  \brief This methods allows to change the way the simulation progresses.
+		  If the input value is 0 (false), the simulation will advance a single time 
+		  step for each call to run().
+		  If the input value is 1 (true), the simulation will advance contiuosly, 
+		  waiting the time defined with set_timer() between each step, until all 
+		  processes have terminated, or some error happens. 
+		 */
 		void 	set_mode(const bool&);
+		
+		/**
+		  \return The simulation advancement mode: 0 if step-to-step, 1 if
+		  continue.
+		 */
 		bool 	get_mode() const;		
 		
+		/**
+		  \brief Setup the policy to be used by the system.
+		  The input pointer must be one of those returned by get_avaiable_policies().
+		 */
 		void	set_policy(Policy*);
+		
+		/**
+		  \return The policy currently in use.
+		 */
 		Policy* get_policy();
+		
+		/**
+		  \return A collection of policies (scheduling algorithms), from which a user
+		  may choose.
+		 */
 		std::vector<Policy*> get_avaiable_policies();
 		
 		
@@ -76,3 +159,4 @@ namespace sgpem
 
 
 #endif
+