- added doxygen documentation

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

src/backend/observed_subject.hh

@@ -30,19 +30,38 @@
 
 namespace sgpem
 {
-  /**
+
-     Abstract class which represents an observed entity who calls Update() in all Observer objects.
-     See "Observer Pattern" for more information.
-  */
   class ObservedSubject;
 
+  /** \brief Represents an observed entity.
+
+		Abstract class which represents an observed entity. It calls Update() in all Observer objects
+		which are attached to it. See the "Observer Pattern" for more informations.
+  */
   class SG_DLLEXPORT ObservedSubject
   {
   public:
     virtual ~ObservedSubject() =0;
 
+    /**
+		This method calls Update() on each attached Observer. It should be called when the internal state
+		of the ObservedSubject is changed and Observers have to be updated.
+    */
     void notify();
+
+
+    /**
+    	\brief Adds an Observer object to the internal list.
+    */
     void attach(sgpem::Observer*);
+
+
+    /**
+    	\brief Removes an Observer object from the internal list.
+
+    	\returns TRUE if the Observer object has been previously attached (is found in the list);
+    	\returns FALSE otherwise.
+    */
     bool detach(sgpem::Observer*);
 
   private:

src/backend/policy_parameters.hh

@@ -38,9 +38,10 @@ namespace sgpem
 	class PolicyParameters;
 
 
-  /**	\brief 
+  /** \brief Represents all configurable parameters of a single scheduling policy.
-		Represents all configurable parameters of a single scheduling algorithm. Is is used by the user
+
-  		interface: it's useful to know which parameters the user will be asked for.		  
+  		Represents all configurable parameters of a single scheduling policy. Is is used by the user
+  		interface: it serves to know which parameters the user will be asked for.
   		Each Policy object owns only one instance of this class.
   */
 	class SG_DLLEXPORT PolicyParameters
@@ -49,29 +50,132 @@ namespace sgpem
 		template<typename T>
 		class Parameter;
 
+	//#######################################
+	//########## methods to CREATE PARAMETERS
+	//#######################################
 
-		//methods to CREATE PARAMETERS
+		/**\brief Registers an INTEGER parameter.
+
+			This method adds an INTEGER parameter to the list of parameters represented by this class.
+
+			\warning If a parameter named \e name already exists it will be replaced by this one.
+			\param name The name of the parameter. This string will be used to refer to this parameter
+				in the methods set_int(...), get_int(...) and get_registered_int_parameters(...).
+			\param lower_bound The lower limitation of the value which can be set with set_int(...).
+			\param upper_bound The upper limitation of the value which can be set with set_int(...).
+			\param required Denotes if this parameter is required by the policy.
+			\param default_value The initial value of this parameter. (If not specified it's set to 0).
+		*/
 		void	register_int(Glib::ustring name,const int& lower_bound, const int& upper_bound, const bool& required, const int& default_value = 0);
+
+		/**\brief Registers a FLOAT parameter.
+
+			This method adds a FLOAT parameter to the list of parameters represented by this class.
+
+			\warning If a parameter named \e name already exists it will be replaced by this one.
+			\param name The name of the parameter. This string will be used to refer to this parameter
+				in the methods set_float(...), get_float(...) and get_registered_float_parameters(...).
+			\param lower_bound The lower limitation of the value which can be set with set_int(...).
+			\param upper_bound The upper limitation of the value which can be set with set_int(...).
+			\param required Denotes if this parameter is required by the policy.
+			\param default_value The initial value of this parameter. (If not specified it's set to 0.0f).
+		*/
 		void	register_float(Glib::ustring name,const float& lower_bound, const float& upper_bound, const bool& required, const float& default_value = 0.0f);
+
+		/**\brief Registers a STRING parameter.
+
+			This method adds a STRING parameter to the list of parameters represented by this class.
+			Note that there are no limitations to the value thath this parameter can assume.
+
+			\warning If a parameter named \e name already exists it will be replaced by this one.
+			\param name The name of the parameter. This string will be used to refer to this parameter
+				in the methods set_string(...), get_string(...) and get_registered_string_parameters(...).
+			\param required Denotes if this parameter is required by the policy.
+			\param default_value The initial value of this parameter. (If not specified it's set to the empty string).
+		*/
 		void	register_string(Glib::ustring name, const bool& required, const Glib::ustring& default_value = "");
 
+
+		/**\brief Deletes all registered parameters.
+		*/
 		void	clear();
 
-		//methods to RETRIEVE CREATED PARAMETERS
+
+	//#############################################
+	//###### methods to RETRIEVE CREATED PARAMETERS
+	//#############################################
+
+		/** \brief Permits to retrieve all registered INTEGER parameters
+			\returns a map of INTEGER parameters identfied by their name
+		*/
 		std::map<Glib::ustring, Parameter<int> > 			get_registered_int_parameters() const;
+
+		/** \brief Permits to retrieve all registered FLOAT parameters
+			\returns a map of FLOAT parameters identfied by their name
+		*/
 		std::map<Glib::ustring, Parameter<float> > 			get_registered_float_parameters() const;
+
+		/** \brief Permits to retrieve all registered STRING parameters
+			\returns a map of STRING parameters identfied by their name
+		*/
 		std::map<Glib::ustring, Parameter<Glib::ustring> > 	get_registered_string_parameters() const;
 
-		//methods to SET the VALUE of PARAMETERS
 
+	//#############################################
+	//###### methods to SET the VALUE of PARAMETERS
+	//#############################################
+
+		/** \brief Sets the value of a registred INTEGER parameter
+
+			Permits to change the value of a parameter identified by "name"
+
+			\returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't
+				exceed the bounds proper to that parameter
+			\returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds
+		*/
 		bool 	set_int(Glib::ustring name, const int& value);
+
+		/** \brief Sets the value of a registred FLOAT parameter
+
+			Permits to change the value of a parameter identified by "name"
+
+			\returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't
+				exceed the bounds proper to that parameter
+			\returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds
+		*/
 		bool 	set_float(Glib::ustring name, const float& value);
+
+		/** \brief Sets the value of a registred STRING parameter
+
+			Permits to change the value of a parameter identified by "name"
+
+			\returns TRUE if the specified "name" maps to a registered parameter and if "value" doesn't
+				exceed the bounds proper to that parameter
+			\returns FALSE if the parameter named "name" is not found or if "value" exceeds the bounds
+		*/
 		bool 	set_string(Glib::ustring name, const Glib::ustring& value);
 
-		//methods to GET the VALUE of PARAMETERS
 
+	//#############################################
+	//###### methods to GET the VALUE of PARAMETERS
+	//#############################################
+
+		/** \brief Returns the value of an INTEGER parameter
+			\returns the INTEGER value of the parameter named \e name
+			\throws PolicyParametersException if the parameter named \e name has not been registered
+		*/
 		int					get_int(Glib::ustring name) const;
+
+		/** \brief Returns the value of an FLOAT parameter
+			\returns the FLOAT value of the parameter named \e name
+			\throws PolicyParametersException if the parameter named \e name has not been registered
+		*/
 		float 				get_float(Glib::ustring name) const;
+
+		/** \brief Returns the value of an STRING parameter
+			\returns the STRING value of the parameter named \e name
+			\throws PolicyParametersException if the parameter named \e name has not been registered
+		*/
 		Glib::ustring 		get_string(Glib::ustring name) const;
 
 
@@ -83,7 +187,8 @@ namespace sgpem
 	};
 
 
-	/**
+	/** \brief This class represents a sigle parameter of type \c T
+
 		This class is useful only to store informations about each parameter. No checks
 		on the values entered are done.
 	*/
@@ -91,14 +196,45 @@ namespace sgpem
 	class PolicyParameters::Parameter
 	{
 		public:
+
+			/** \brief Constructs the parameter
+				\param name The name of the parameter. This string will be used to refer to this parameter, thus it MUST
+					be uniqe (one string identifies \b only ONE parameter)
+				\param value The initial value of this parameter
+				\param lower_bound The lower limitation of the value which can be set with set_int(...).
+				\param upper_bound The upper limitation of the value which can be set with set_int(...).
+				\param required Denotes if this parameter is required by the policy.
+				\param default_value The initial value of this parameter. (If not specified it's set to 0).
+			*/
 			Parameter(Glib::ustring name, const T& value, const T& lower_bound, const T& upper_bound, const bool& required,  const T& default_value = 0);
+
+			/** \returns The name of the parameter (its UNIQUE key)
+			*/
 			Glib::ustring	get_name() const;
+
+			/** \returns The lower bound
+			*/
 			T				get_lower_bound() const;
+
+			/** \returns The upper bound
+			*/
 			T				get_upper_bound() const;
+
+			/** \returns TRUE if this parameter is required
+			*/
 			bool			is_required() const;
+
+			/** \returns Its default value
+			*/
 			T				get_default() const;
+
+			/** \returns Its actual value
+			*/
 			T				get_value() const;
 
+			/** \brief Changes the value of the parameter.
+				\warning NO CHECK is done whether the value repects its bounds!!
+			*/
 			void 			set_value(const T&);
 
 		private:

src/backend/pyloader/python_policy.hh

@@ -37,6 +37,11 @@ namespace sgpem
   class PythonPolicyManager;
   class UserInterruptException;
 
+	/** \brief A specialization of abstract class Policy
+
+		This class represents a policy written in Python. Its methods interact with Python interpreter.
+		See the documentation of class Policy for more detailed informations.
+	*/
   class SG_DLLEXPORT PythonPolicy : public Policy
   {
   public:
@@ -45,13 +50,36 @@ namespace sgpem
 
     virtual ~PythonPolicy();
 
+	/**
+		Calls the method \c async_configure
+	*/
     void			configure() throw(UserInterruptException);
+
+    /**
+    	Calls the method \c async_sort_queue
+    */
     void 			sort_queue(Scheduler::event) const throw(UserInterruptException);
+
+    /**
+    	\returns A textual description of this policy.
+    */
     Glib::ustring 	        get_description() const;
+
+    /**
+    	\returns \c TRUE if the policy is preemptive.
+    	\returns \c FALSE if the policy is not preemptive.
+    */
     bool 			is_pre_emptive() const throw(UserInterruptException);
+
+    /**
+    	\returns The integer value of its time-slice.
+    */
     int              get_time_slice() const throw(UserInterruptException);
 
     // Singing with Caipha's voice: "must die, must die, this method must die!"
+    /**
+    	Changes the time-slice of the policy.
+    */
     void 			set_time_slice(const int&);
 
   private:

src/backend/string_utils.hh

@@ -26,13 +26,37 @@
 #include <iostream>
 #include "glibmm/ustring.h"
 
+	/**\brief This function tries to convert a string into an integer value.
 
+		The string can contain only digits and the minus character (for negative numbers).
+
+		\returns TRUE if ths string represent a valid integer number
+		\returns FALSE otherwise
+	*/
 	bool SG_DLLEXPORT string_to_int(const Glib::ustring&, int&);
 
+
+	/**\brief This function converts an integer value into a string.
+
+		There is no return value because this function always succeeds.
+	*/
 	void SG_DLLEXPORT int_to_string(const int&, Glib::ustring&);
 
+
+	/**\brief This function converts a float value into a string.
+
+		There is no return value because this function always succeeds.
+	*/
 	void SG_DLLEXPORT float_to_string(const float&, Glib::ustring&);
 
+
+	/**\brief This function tries to convert a string into a float value.
+
+		The string can contain only digits, the minus, plus and dot (-+.) characters. If not,
+		the value 0 is assigned.
+
+		There is no return value because this function always succeeds, even if the string is badly formed.
+	*/
 	void SG_DLLEXPORT string_to_float(const Glib::ustring&, float&);