- Completed my part of auditing

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

plugins/xmlsave/src/plugin.cc

@@ -20,9 +20,10 @@
 
 #include "config.h"
 
-#include <sgpemv2/plugin.hh>
 #include "xml_serializer.hh"
 
+#include <sgpemv2/plugin.hh>
+
 using namespace sgpem;
 
 sgpem::XMLSerializer* _serializer = NULL;

src/add_request_dialog.hh

@@ -25,10 +25,9 @@ namespace sgpem
 {
   class Request;
   class Thread;
+  class AddRequestDialog;
 }  
 
-
-
 #include <gtkmm/treeview.h>
 #include <gtkmm/liststore.h>
 #include <gtkmm/dialog.h>
@@ -38,32 +37,70 @@ namespace sgpem
 
 namespace sgpem
 {
+  /** \brief A dialog derived from add-request-dialog.glade
+   *
+   * Manages the list of subrequests, ensures only "nonempty" requests
+   * are created, and supports also editing.
+   */ 
   class AddRequestDialog : public Gtk::Dialog
   {
   public:
+    /** \brief Constructor required by libglademm
+     */
     AddRequestDialog(BaseObjectType* cobject, const Glib::RefPtr<Gnome::Glade::Xml>& glade);
 
-    /** 
-      \brief Attemts to show the dialog, and constructs a request 
-      if response is OK 
-      \param owner The thread which will own the request
+    /** \brief Attemts to show the dialog, and constructs a new request 
+      * if response is OK 
+      * \param owner The thread which will own the request
+      * \return A pointer to the created request, or NULL if the request
+      * wasn't created
       */
     Request* run_add(Thread& owner);
     
-    /** 
-      \brief Attemts to show the dialog, and modify an existing request 
-      if response is OK 
-      \param resource The request to modify
+    /** \brief Attemts to show the dialog to modify an existing request
+      * \param request The request to modify
       */
-    void run_edit(Request& resource);
+    void run_edit(Request& request);
     
   private:
+    /** \brief Fills the combo model with data from the latest
+     * Environment
+     */
     void update_combo();
+
+    /** \brief Called when the "add subrequest" button is pressed
+     */
     void _on_add();
+    
+    /** \brief Called when the "remove subrequest" button is pressed
+     */
     void _on_remove();
+
+    /** \brief Called when list selection changes 
+     * 
+     * Ensures the "remove subrequest" button is sensitive only
+     * if a subrequest is selected
+     */
     void _on_list_selection_changed();
+
+    /** \brief Called when a row is added to the subrequest list
+     *
+     * Ensures the OK button is sensitive since we are sure there is at
+     * least a subrequest
+     */
     void _on_row_added(const Gtk::TreePath& path, const Gtk::TreeIter& it);
+    
+    /** \brief Called when a row is removed from the subrequest list
+     *
+     * Ensures the OK button is no more sensitive if the last item was removed
+     */
     void _on_row_removed(const Gtk::TreePath& path);
+    
+    /** \brief Called when the combo selection changes 
+     * 
+     * Ensures the "add subrequest" button is sensitive only
+     * if a resource is selected
+     */
     void _on_combo_selection_changed();
     
     Glib::RefPtr<Gnome::Glade::Xml> _glade;

src/backend/dynamic_sub_request.hh

@@ -21,36 +21,60 @@
 #ifndef DYNAMIC_SUB_REQUEST_HH
 #define DYNAMIC_SUB_REQUEST_HH 1
 
-
-
-#include <sgpemv2/request.hh>
-#include <sgpemv2/sub_request.hh>
-#include "dynamic_request.hh"
-#include "dynamic_resource.hh"
-#include "static_sub_request.hh"
-
-#include <sgpemv2/templates/smartp.hh>
-
 namespace sgpem
 {
   class DynamicSubRequest;
   class SerializeVisitor;
   class Resource;
   class StaticSubRequest;
+}
 
+#include "dynamic_request.hh"
+#include "dynamic_resource.hh"
+#include "static_sub_request.hh"
+
+#include <sgpemv2/request.hh>
+#include <sgpemv2/sub_request.hh>
+#include <sgpemv2/templates/smartp.hh>
+
+namespace sgpem
+{
+  /** \brief Represents the dynamic status of a subrequest
+   */
   class SG_DLLLOCAL DynamicSubRequest : public SubRequest
   {
   public:
-    DynamicSubRequest(StaticSubRequest* core,
-                      DynamicRequest* owner);
+    /** \brief Constructor
+     *
+     * Only ::History knows how to use this :-).
+     */
+    DynamicSubRequest(StaticSubRequest* core, DynamicRequest* owner);
+
+    /** \brief "Special" copy constructor, which copies everything except owner
+     * \param owner The owner of the new DynamicSubRequest
+     */
     DynamicSubRequest(const DynamicSubRequest& other, DynamicRequest* owner);
 
     virtual ~DynamicSubRequest();
 
+    /** \brief Tells if this object equals another of the same type
+     *
+     * \return true If they own a reference to the same Static object
+     * \return false Otherwise
+     */
     virtual bool operator==(const SubRequest& op2) const;
     
+    /** \brief Returns the key to the DynamicResource that was requested
+     *
+     * The correct ::Resource object can be obtained via 
+     * Environment.get_resources(), using the returned value as a key
+     */
     resource_key_t get_resource_key() const;
     
+    /** \brief Returns the time the resource is needed
+     *
+     * This time is meant relative to a process executed time.
+     */
     unsigned int get_length() const;
 
     int get_queue_position() const;
@@ -62,6 +86,9 @@ namespace sgpem
     state set_state(state new_state);
 
     unsigned int get_remaining_time() const;
+
+    /** \brief Decreases remaining time by 1
+     */
     unsigned int decrease_remaining_time();
 
     void serialize(SerializeVisitor& translator) const;

src/backend/sgpemv2/history_observer.hh

@@ -1,4 +1,4 @@
-// src/backend/history_observer.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/history_observer.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -21,16 +21,28 @@
 #ifndef HISTORY_OBSERVER_HH
 #define HISTORY_OBSERVER_HH 1
 
-#include <sgpemv2/sgpemv2-visibility.hh>
-
 namespace sgpem
 {
   class History;
   class HistoryObserver;
+}
 
+#include <sgpemv2/sgpemv2-visibility.hh>
+
+namespace sgpem
+{
+  /** \brief Specifies that the object wants to be notified 
+   * whenever backend::History changes
+   *
+   * Observers need to register to an History if they want to be
+   * notified.
+   * \see History
+   */
   class SG_DLLEXPORT HistoryObserver
   {
   public:
+    /** \brief Called on an History update 
+     */
     virtual void update(const History& changed_history) = 0;
     virtual ~HistoryObserver();
 

src/cairo_widget.hh

@@ -21,8 +21,6 @@
 #ifndef CAIRO_WIDGET_HH
 #define CAIRO_WIDGET_HH 1
 
-
-
 #include <cairo.h>
 #include <gtkmm/drawingarea.h>
 #include <gtkmm/widget.h>

src/holt_container_window.hh

@@ -24,23 +24,20 @@
 
 #include "gettext.h"
 
+#include "cairo_widget.hh"
+#include "holt_widget.hh"
+
+#include <sgpemv2/simulation.hh>
+
 #include <gtkmm/window.h>
 
 #include <cassert>
 #include <iostream>
 
-#include <sgpemv2/simulation.hh>
-#include "cairo_widget.hh"
-#include "holt_widget.hh"
-
-namespace sgpem {
-  // ------------------------------------------------------
-  //
-  // HoltContainerWindow class
-  //
-  // contains and controls the tested holt widget
-  //
-  // ------------------------------------------------------
+namespace sgpem 
+{
+  /** \brief Contains and controls the holt widget
+   */
   class HoltContainerWindow : public Gtk::Window
   {
   public:

src/main.cc

@@ -42,6 +42,8 @@ main(int argc, char* argv[])
   using namespace std;
   using Glib::ustring;
 
+  // FIXME disable gettext in Windows under Visual Studio
+  // we currently have no time to port also this thing
 #ifndef _MSC_VER
   // Set up gettext support
   setlocale(LC_ALL, "");
@@ -49,6 +51,9 @@ main(int argc, char* argv[])
   textdomain(PACKAGE);
 #endif
 
+  // mainly for debugging in Windows, where the type and
+  // content of uncaught exceptions is not easily 
+  // obtainable
 #ifndef NDEBUG
   try
   {

src/testsuite/test-key_file.cc

@@ -1,4 +1,4 @@
-// src/testsuite/test-stepforward.cc - Copyright 2005, 2006, University
+// src/testsuite/test-key_file.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -21,15 +21,12 @@
 /* This executable tests for workingness of the save preferences method,
  * and nothing else. */
 
-
-#include "glibmm/ustring.h"
 #include <sgpemv2/key_file.hh>
+
+#include <glibmm/ustring.h>
+
 #include <iostream>
 
-
-
-// from here and further until the bottom, all to throw away I suppose
-
 int
 main(int argc, char** argv)
 {