- More audited files. No more headers for me to audit.

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

src/backend/dynamic_resource.hh

@@ -31,6 +31,24 @@
 
 namespace sgpem
 {
+
+
+  /// \brief Desribes the state of a resource entity in a particular moment
+  /// of the simulation.
+  ///
+  /// Contains part of the information used by the scheduling policies to 
+  /// perform scheduling.
+  /// DynamicResource objects may be created by the system
+  /// via the Scheduler.step_forward() method (which then inserts them into a 
+  /// ::ConcreteEnvironment), or by the user on a resetted ::History by creating
+  /// one of them anew.
+  /// 
+  /// Actually this class does not provide any information to the system, nor it
+  /// does play any particular role. It is here for the puropose of extensibility
+  /// and beauty in general.
+  /// 
+  /// These objects may be destroyed only by resetting an ::History, or via one 
+  /// of its methods.
   class DynamicResource;
   class SerializeVisitor;
 
@@ -41,12 +59,34 @@ namespace sgpem
 
     virtual bool operator==(const Resource& op2) const;
 
+    /// \brief Returns the name of the Resource.
+    ///
+    /// Returns the name of the Resource.
+    /// \return the name of the Resource.
     Glib::ustring get_name() const;
+
+    /// \brief Returns the number of places of the Resource.
+    ///
+    /// Returns the number of places of the Resource.
+    /// \return the number of places of the Resource.
     unsigned int get_places() const;
 
+
+    /// \brief Serializes this object via the provided translator.
+    /// 
+    /// Calls translator->from_resource(this).
     void serialize(SerializeVisitor& translator) const;
 
+    /// \brief Returns a reference to the static resource object.
+    /// 
+    /// This function returns a reference to the actual schedable object
+    /// represented, along with its status, by this instance.
     StaticResource& get_core();
+
+    /// \brief Returns a constant reference to the static schedulable object.
+    /// 
+    /// This function returns a constant reference to the actual schedable object
+    /// represented, along with its status, by this instance.
     const StaticResource& get_core() const;
 
   private:

src/backend/dynamic_schedulable.hh

@@ -29,7 +29,7 @@ namespace sgpem
 {
 
   /// \brief Desribes the state of a schedulable entity in a particular moment
-  /// of the simulation
+  /// of the simulation.
   ///
   /// Contains part of the information used by the scheduling policies to 
   /// perform scheduling.
@@ -152,22 +152,22 @@ namespace sgpem
     /// \brief Returns the elapsed time of the Schedulable.
     ///
     /// Returns the elapsed time of the Schedulable.
-    /// The elapsed time is the amount of time a Schedulable has been running
+    /// The elapsed time is the amount of time a Schedulable has been running.
     /// until the current instant.
     ///
     /// The elapsed time is a dynamic (respect to the simulation) property.
     /// \return the elapsed time of the Schedulable.
     virtual unsigned int get_elapsed_time() const = 0;
 
-    /// \brief Returns a pointer to the static schedulable object
+    /// \brief Returns a reference to the static schedulable object.
     /// 
-    /// This function returns a reference to the actual schedable object
+    /// This function returns a reference to the actual schedable object.
     /// represented, along with its status, by this instance.
     virtual StaticSchedulable& get_core() = 0;
 
-    /// \brief Returns a constant pointer to the static schedulable object
+    /// \brief Returns a constant reference to the static schedulable object.
     /// 
-    /// This function returns a constant reference to the actual schedable object
+    /// This function returns a constant reference to the actual schedable object.
     /// represented, along with its status, by this instance.
     virtual const StaticSchedulable& get_core() const = 0;
 

src/resources_widget.hh

@@ -40,33 +40,89 @@ namespace sgpem
 
 namespace sgpem
 {
+  /// \brief A ResourcesWidget displays the resources during the simulation 
+  /// and lets the user modify them.
+  ///
+  /// A ResourceWidget is a Gtk::Treewidget customized with the aim of
+  /// representing resources and their inner queues.
+  /// As an editor, the widget allows the user to select a resource and
+  /// modify it pressing the left mouse button over it.
+  ///
+  /// A ResourcesWidget is also a HistoryObserver, which means that it is
+  /// automatically updated at every notified update of the History.
   class ResourcesWidget : public Gtk::TreeView, public HistoryObserver
   {
   public:
+    /** \brief Constructor required by libglademm
+     */
     ResourcesWidget(BaseObjectType* cobject, const Glib::RefPtr<Gnome::Glade::Xml>& glade);
+
+    /// \brief Standard virtual destructor.
+    ///
     virtual ~ResourcesWidget();
 
+    /// \brief updates the widget with the new content of the notifying History
+    ///
+    /// \param history the notifying history.
     virtual void update(const History& history);
     
+    /// \brief Manages the mouse button press event.
+    /// 
+    /// This method pops up a menu and offers the user the tools to modify or add a resource.
+    /// \param event the event to manage.
     bool on_button_press_event(GdkEventButton* event);
 
   private:
+    /// \brief a CellRenderer which allows rhe rendering of
+    /// marked-up text.
+    ///
+    /// This class allows the customization of the text displayed
+    /// inside the lines of the TreeView.
     class CellRendererTextMarkup : public Gtk::CellRendererText
     {
       public:
-	Glib::PropertyProxy_Base _property_renderable();
+        /// \brief Customize this to render the text.
+        Glib::PropertyProxy_Base _property_renderable();
     };
 
+    /// \brief Returns the current selection via the in/out parameter selection.
+    /// \param selection the parameter where the current selection will be set
+    /// \return \c true if the selection is valid, \c false otherwise
     bool get_selected_key(unsigned int& selection);
     
+    /// \brief Returns the selected Resource.
+    ///
+    /// Returns the selected Resource.
+    /// \return a pointer to the selected Resource
     Resource* get_selected_resource();
 
+    /// \brief Manages the user choice of adding a resoure.
+    ///
+    /// Calls add_edit_resource.
+    /// Displays a popup dialog which asks for details of the new resource.
     void _on_add_resource();
+
+    /// \brief Manages the user choice of editing a resoure.
+    ///
+    /// Calls add_edit_resource.
+    /// Displays a popup dialog which asks for details of the edited resource.
     void _on_edit_resource();
+
+    /// \brief Manages the user choice of adding or editing a resoure.
+    ///
+    /// Displays a popup dialog which asks for details of the new or edited resource.
     void add_edit_resource(bool adding);
-    
+
+    /// \brief Manages the user choice of removing a resoure.
+    ///
+    /// Calls add_edit_resource.
+    /// Displays a popup dialog which asks for details of the new resource.    
     void _on_remove_resource();
     
+    /// \brief Updates the cell text with proper rendering.
+    /// 
+    /// \param cr the cell renderer used to render
+    /// \param it an iterator over the underlying model
     void _on_cell_name_data(Gtk::CellRenderer* cr, 
                             const Gtk::TreeModel::iterator& it);
     

src/schedulables_statistics_widget.hh

@@ -31,66 +31,123 @@
 
 namespace sgpem
 {
+  /// \brief A widget showing a table with simulation statistics
+  /// 
+  /// This class represents a widget which displays a table
+  /// containing all sorts of simulation statistics.
+  /// Values are either strings, booleans or integers.
+  /// The widget may be customized using setter and getters for
+  /// specific columns.
+  class TabularSchedulableStatisticsWidget : public HistoryObserver, public Gtk::TreeView
+  {	
+  public:
+    /// \brief Standard constructor.
+    ///
+    TabularSchedulableStatisticsWidget();
 
+    /// \brief Standard virtual destructor.
+    ///
+    virtual ~TabularSchedulableStatisticsWidget();
+
+    /// \brief Updates the table with values adherent with the changed history.
+    /// \param changed_history the history which notified a change.
+    void update(const History& changed_history);
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_runs(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_runs() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_perc(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_perc() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_inactive(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_inactive() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_turn_around(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_turn_around() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_response(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_response() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_efficiency(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_efficiency() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_resource_usage(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_resource_usage() const;
+
+    /// \brief Sets the column visibile.
+    ///
+    void set_show_resource_block(bool);
+
+    /// \brief Gets whether the column is visibile.
+    ///
+    bool get_show_resource_block() const;
+
+  protected:
+    /// \brief Main helper method which updates the columns of the widget
+    /// on the basis of the underlying model.
+    void update_columns();
 	
-	class TabularSchedulableStatisticsWidget : public HistoryObserver, public Gtk::TreeView
+    bool _show_runs;
-	{	
+    bool _show_perc;
-	public:	
+    bool _show_inactive;
-		TabularSchedulableStatisticsWidget();
+    bool _show_turn;
-		virtual ~TabularSchedulableStatisticsWidget();
+    bool _show_resp;
-		
+    bool _show_effic;
-		void 		update(const History& changed_history);
+    bool _show_ris_usage;
-		
+    bool _show_ris_block;
-		void		set_show_runs(bool);
-		bool		get_show_runs() const;
-		
-		void		set_show_perc(bool);
-		bool		get_show_perc() const;
-		
-		void		set_show_inactive(bool);
-		bool		get_show_inactive() const;
 
-		void		set_show_turn_around(bool);
+    // treeview stuffs
-		bool		get_show_turn_around() const;
+    Glib::RefPtr<Gtk::TreeStore> _model;
-		
+    Gtk::TreeModelColumnRecord _columns;
-		void		set_show_response(bool);
-		bool		get_show_response() const;
 
-		void		set_show_efficiency(bool);
+    // all columns
-		bool		get_show_efficiency() const;
+    Gtk::TreeModelColumn<Glib::ustring>  _col_name;
+    Gtk::TreeModelColumn<int>            _col_runs;
+    Gtk::TreeModelColumn<Glib::ustring>  _col_perc;
+    Gtk::TreeModelColumn<int>            _col_inactive;
+    Gtk::TreeModelColumn<int>            _col_turn;
+    Gtk::TreeModelColumn<Glib::ustring>  _col_resp;
+    Gtk::TreeModelColumn<Glib::ustring>  _col_effic;
+    Gtk::TreeModelColumn<int>            _col_ris_usage;
+    Gtk::TreeModelColumn<int>            _col_ris_block;
 
-		void		set_show_resource_usage(bool);
+  }
-		bool		get_show_resource_usage() const;
+  ;
-
-		void		set_show_resource_block(bool);
-		bool		get_show_resource_block() const;
-
-	protected:
-		void 								update_columns();
-		
-		bool 								_show_runs,			//which info to show
-											_show_perc,
-											_show_inactive,
-											_show_turn,
-											_show_resp,
-											_show_effic,
-											_show_ris_usage,
-											_show_ris_block;
-											
-		Glib::RefPtr<Gtk::TreeStore> 		_model;				//treeview stuffs
-		Gtk::TreeModelColumnRecord 			_columns;
-		
-		Gtk::TreeModelColumn<Glib::ustring> _col_name;			//all columns
-		Gtk::TreeModelColumn<int>			_col_runs;
-		Gtk::TreeModelColumn<Glib::ustring>	_col_perc;
-		Gtk::TreeModelColumn<int>			_col_inactive;
-		Gtk::TreeModelColumn<int>			_col_turn;
-		Gtk::TreeModelColumn<Glib::ustring>	_col_resp;
-		Gtk::TreeModelColumn<Glib::ustring>	_col_effic;
-		Gtk::TreeModelColumn<int>			_col_ris_usage;
-		Gtk::TreeModelColumn<int>			_col_ris_block;
-	
-	};
 
 } //~ namespace sgpem
 

src/simulation_widget.cc

@@ -117,7 +117,7 @@ SimulationWidget::update(const History&  /* changed_history */  )
 
 
 bool
-SimulationWidget::get_show_threads()
+SimulationWidget::get_show_threads() const
 {
   return _show_threads;
 }

src/simulation_widget.hh

@@ -97,7 +97,7 @@ namespace sgpem
      *
      * \return true if threads visualization is enabled
      */
-    bool get_show_threads();
+    bool get_show_threads() const;
 
     /**
      * \brief Sets and gets the _show_threads flag status.

src/text_simulation.hh

@@ -69,52 +69,172 @@ namespace sgpem
      */
     virtual void update(const Simulation& changed_simulation);
 
+    /// \brief Chechks if the number of arguments is the one exepected.
+    /// 
+    /// \param arguments the arguments
+    /// \param num the expected number of parameters
+    /// \return whether the number of arguments is the one expected or not
     bool check_arguments_num(const Tokens& arguments, unsigned int num);
+
+    /// \brief Checks if the environment is unsaved and asks for confirmation.
+    ///
     bool unsaved_ask_confirm() const;
+
+    /// \brief Prints out the content of a container, depending on its content.
+    /// \param entities the container to print
     template <typename Container>
     void show(const Container& entities);
+
+    /// \brief Reads a parameter from the standard input.
+    /// \param parameter the parameter to get filled
     template <typename T>
     void get_parameter(CommandParameter<T>& parameter);
+
+    /// \brief Configures the policy
+    /// \param the policy to configure
     template <typename PolicyType>
     void configure_policy(PolicyType& policy);
+
+    /// \brief Prints out the policies which are available within the system
+    /// \param arguments an unused parameter
     template <typename GatekeeperType>
     void show_policies(const Tokens& arguments);
     
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_run(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_pause(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_jumpto(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_stop(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_configure(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_help(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_quit(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_get(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_set(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_processes(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_resources(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_threads(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_requests(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_subrequests(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_cpu_policies(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_resource_policies(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_show_statistics(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add_process(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add_resource(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add_thread(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add_request(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_add_subrequest(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove_process(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove_resource(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove_thread(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove_request(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_remove_subrequest(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_save(const Tokens& arguments);
+
+    /// \brief Executes the command.
+    /// \param arguments the arguments of the command
     void on_load(const Tokens& arguments);
 
+    /// \brief Helper funcion which prints a string to the standard output.
     static void p_stdout(const Glib::ustring& str);
+
+    /// \brief Helper funcion which prints a string to the standard output for errors.
     static void p_stderr(const Glib::ustring& str);
+
+    /// \brief Helper funcion which reads a line from the standard input.
     static Glib::ustring readline();
 
     bool _saved;