diff --git a/plugins/pyloader/src/builtin-policies/fcfs.py b/plugins/pyloader/src/builtin-policies/fcfs.py
index 156549f..a5d432c 100644
--- a/plugins/pyloader/src/builtin-policies/fcfs.py
+++ b/plugins/pyloader/src/builtin-policies/fcfs.py
@@ -1,4 +1,4 @@
-# src/builtin-policies/fcfs.py - Copyright 2005, 2006, University
+# plugins/pyloader/src/builtin-policies/fcfs.py - Copyright 2005, 2006, University
 #                            of Padova, dept. of Pure and Applied
 #                            Mathematics
 #
diff --git a/plugins/pyloader/src/plugin.cc b/plugins/pyloader/src/plugin.cc
index 8381b86..0c7537f 100644
--- a/plugins/pyloader/src/plugin.cc
+++ b/plugins/pyloader/src/plugin.cc
@@ -1,4 +1,4 @@
-// src/plugin.cc - Copyright 2005, 2006, University
+// plugins/pyloader/src/plugin.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
diff --git a/plugins/pyloader/src/python_cpu_policy.cc b/plugins/pyloader/src/python_cpu_policy.cc
index 5ee728c..a0bc4b3 100644
--- a/plugins/pyloader/src/python_cpu_policy.cc
+++ b/plugins/pyloader/src/python_cpu_policy.cc
@@ -1,4 +1,4 @@
-// src/python_cpu_policy.cc - Copyright 2005, 2006, University
+// plugins/pyloader/src/python_cpu_policy.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
diff --git a/plugins/pyloader/src/testsuite/python_loader_configure.py b/plugins/pyloader/src/testsuite/python_loader_configure.py
index fd87ddf..092d430 100644
--- a/plugins/pyloader/src/testsuite/python_loader_configure.py
+++ b/plugins/pyloader/src/testsuite/python_loader_configure.py
@@ -1,3 +1,23 @@
+# plugins/pyloader/src/testsuite/python_loader_configure.py - Copyright 2005, 2006, University
+#                            of Padova, dept. of Pure and Applied
+#                            Mathematics
+#
+# This file is part of SGPEMv2.
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# SGPEMv2 is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with SGPEMv2; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
 from CPUPolicy import CPUPolicy
 import sys
 
diff --git a/plugins/pyloader/src/testsuite/python_loader_is_preemptive.py b/plugins/pyloader/src/testsuite/python_loader_is_preemptive.py
index d0fe3bf..060aa2d 100644
--- a/plugins/pyloader/src/testsuite/python_loader_is_preemptive.py
+++ b/plugins/pyloader/src/testsuite/python_loader_is_preemptive.py
@@ -1,3 +1,23 @@
+# plugins/pyloader/src/testsuite/python_loader_is_preemptive.py - Copyright 2005, 2006, University
+#                            of Padova, dept. of Pure and Applied
+#                            Mathematics
+#
+# This file is part of SGPEMv2.
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# SGPEMv2 is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with SGPEMv2; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
 from CPUPolicy import CPUPolicy
 import sys
 
diff --git a/plugins/xmlsave/src/xml_serializer.hh b/plugins/xmlsave/src/xml_serializer.hh
index 3c81a34..13bab80 100644
--- a/plugins/xmlsave/src/xml_serializer.hh
+++ b/plugins/xmlsave/src/xml_serializer.hh
@@ -1,4 +1,4 @@
-// src/backend/serializer.hh - Copyright 2005, 2006, University
+// plugins/xmlsave/src/xml_serializer.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -93,24 +93,6 @@ namespace sgpem
      */
     void fill_doc(xmlDocPtr doc, const History& hist);
 
-    /**
-      \brief Take a resources node and fill it with the data
-
-      For each resource in hist create a "resource" node and fill with data.
-      Uses an XMLVisitor object to do the task.
-     */
-    // void fill_resources(xmlNodePtr resources_node, const History& hist);
-
-    /**
-      \brief Take a schedulables node and fill it with the data
-
-      For each resource in hist create a "schedulable" node and fill with data.
-      Also all schedulable sub nodes are generated too.
-      Uses an XMLVisitor object to do the task.
-     */
-    // void fill_schedulables(xmlNodePtr schedulables_node, const History& hist);
-
-
     /**
       \brief Restore the snapshot from the passed xml document
 
diff --git a/src/backend/environment.cc b/src/backend/environment.cc
index 570c4ae..4654ce9 100644
--- a/src/backend/environment.cc
+++ b/src/backend/environment.cc
@@ -1,4 +1,4 @@
-// src/backend/resource.cc - Copyright 2005, 2006, University
+// cambiare in: src/backend/environment.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
diff --git a/src/backend/sgpemv2/history.hh b/src/backend/sgpemv2/history.hh
index 178c360..2465f33 100644
--- a/src/backend/sgpemv2/history.hh
+++ b/src/backend/sgpemv2/history.hh
@@ -1,4 +1,4 @@
-// src/backend/history.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/history.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -75,75 +75,228 @@ namespace sgpem
     virtual const Environment& get_last_environment() const = 0;
     virtual const Environment& get_environment_at(position index) const throw(std::out_of_range) = 0;
 
+    /**
+    \brief Removes a Resource from the whole History.
+    This normally means that users themselves have asked for a particular
+    ::Resource to be removed by the whole simulation they're editing.
+    Before removal, the History should always be reset().
+
+    \param resource_key The key of the resource to remove.
+    */
     virtual void  remove(resource_key_t resource_key)  = 0;
+
+    /**
+    \brief Removes a Process from the whole History.
+    This normally means that users themselves have asked for a
+    particular ::Process to be removed by the whole simulation they're editing.
+
+    \param process The process to remove.
+    */
     virtual void  remove(Process&    process)          = 0;
+
+    /**
+    \brief Removes a thread from the whole History.
+    This normally means that users themselves have asked for a
+    particular ::Thread to be removed by the whole simulation they're editing.
+
+    \param thread The thread to remove.
+    */
     virtual void  remove(Thread&     thread)           = 0;
+
+    /**
+    \brief Removes a request from the whole History.
+    This normally means that users themselves have asked for a
+    particular ::Request to be removed by the whole simulation
+    they're editing.
+
+    \param request The request to remove.
+    */
     virtual void  remove(Request&    request)          = 0;
+
+    /**
+    \brief Removes a subrequest from the whole History.
+    This normally means that users themselves have asked for a
+    particular ::SubRequest to be removed by the whole simulation
+    they're editing.
+
+    \param subrequest The subrequest to remove.
+    */
     virtual void  remove(SubRequest& subrequest)       = 0;
 
-    // \brief Clears the whole history
+    /**
+      \brief Clears the whole history
+     */
     virtual void clear() = 0;
 
+    /**
+      \brief Add a Resource to the simulation.
+
+      \param name The name of the new resource.
+      \param preemptable True if the resource is preemptable.
+      \param places Number of places of the resource.
+      \param availability The instant from wich the resource is available.
+      \return a pair with unique key and pointer to the resource created.
+     */
     virtual ResourcePair add_resource(const Glib::ustring& name,
                                       bool   preemptable  = false,
                                       size_t places       = 1,
                                       size_t availability = 0) = 0;
 
+    /**
+      \brief Change data of an existing resource.
+
+      \param resource Reference tot the editing resource.
+      \param name The name of the new resource.
+      \param preemptable True if the resource is preemptable.
+      \param places Number of places of the resource.
+      \param availability The instant from wich the resource is available.
+     */
     virtual void        edit_resource(Resource& resource,
                                       const Glib::ustring& name,
                                       bool   preemptable  = false,
                                       size_t places       = 1,
                                       size_t availability = 0) = 0;
 
+    /**
+      \brief Add a Process to the simulation.
+
+      \param name The name of the new process.
+      \param arrival_time Instant when the process starts.
+      \param base_priority Process priority at start up time
+        (scheduler can change it during execution).
+      \return The newly created process.
+     */
     virtual Process&     add_process(const Glib::ustring& name,
                                      time_t arrival_time,
                                      prio_t base_priority = 0) = 0;
 
+    /**
+      \brief Edit an exixting Process in the simulation.
+
+      \param process Reference to the editing process.
+      \param name The name of the new process.
+      \param arrival_time Instant when the process starts.
+      \param base_priority Process priority at start up time
+        (scheduler can change it during execution).
+     */
     virtual void        edit_process(Process& process,
                                      const Glib::ustring& name,
                                      time_t arrival_time,
                                      prio_t base_priority = 0) = 0;
 
 
+    /**
+      \brief Add a Thread to an exixting process.
+
+      \param name The name of the new thread.
+      \param parent Reference to the process wich this thread belongs to.
+      \param cpu_time Total time requested by thread complete execution.
+      \param arrival_time Instant when the thread starts.
+      \param base_priority Thread priority at start up time
+        (scheduler can change it during execution).
+      \return The newly created thread.
+     */
     virtual Thread&      add_thread(const Glib::ustring& name,
                                     Process& parent,
                                     time_t cpu_time,
                                     time_t arrival_time = 0,
                                     prio_t base_priority = 0) = 0;
 
+    /**
+      \brief Edit an exixting Thread in the simulation.
+
+      \param thread Reference to the editing thread.
+      \param name New name for the thread.
+      \param cpu_time Total time requested by thread complete execution.
+      \param arrival_time Instant when the thread starts.
+      \param base_priority Thread priority at start up time
+        (scheduler can change it during execution).
+     */
     virtual void         edit_thread(Thread& thread,
                                      const Glib::ustring& name,
                                      time_t cpu_time,
                                      time_t arrival_time = 0,
                                      prio_t base_priority = 0) = 0;
 
+    /**
+      \brief Add a Request to an existing thread.
+
+      \param owner Reference to the requiring thread.
+      \param instant When the request arrives.
+      \return The newly created request.
+     */
     virtual Request&     add_request(Thread& owner,
                                      time_t instant) = 0;
 
+    /**
+      \brief Edit a Request.
+
+      \param request Reference to editing request.
+      \param instant When the request arrives.
+     */
     virtual void         edit_request(Request& request,
                                       time_t instant) = 0;
 
 
+    /**
+      \brief Add a SubRequest to an existing Request.
+
+      \param owner Reference to the requiring thread.
+      \param resource_key Key of the requested resource.
+      \param duration Total time of request usage.
+      \return The newly created subrequest.
+     */
     virtual SubRequest&  add_subrequest(Request& request,
                                         resource_key_t resource_key,
                                         time_t  duration) = 0;
 
+    /**
+      \brief Edit an existing SubRequest.
+
+      \param subrequest Reference of the request to edit.
+      \param resource_key Key of the requested resource.
+      \param duration Total time of request usage.
+     */
     virtual void         edit_subrequest(SubRequest& subrequest,
                                         resource_key_t resource_key,
                                         time_t  duration) = 0;
+    /**
+     \return actual instant (current time in simulation)
+     */
+    virtual position get_front() const;
 
-		virtual position get_front() const;
-		virtual bool     is_sealed() const = 0;
+    /**
+     */
+    virtual bool     is_sealed() const = 0;
 
+    /**
+    \brief Attach a new observer object for this History.
+    When someone wants to be notified when this object changes,
+    it will register itself to using this method. \b TODO: in next milestones,
+    pass a bitmap to this method so that you can specify exactly for what you
+    want to be notified, e.g. only when resources change but not when requests
+    do, etc.
+    */
     virtual void  attach(HistoryObserver& observer);
-    virtual void  detach(const HistoryObserver& observer);
 
+    /**
+    \brief Detach an observer object for this History. 
+    */
+    virtual void  detach(const HistoryObserver& observer);
+    
+    /**
+    \brief Brings History to initial state.
+    */
     virtual void reset() = 0;
 
   protected:
     typedef std::vector<HistoryObserver*> RegisteredObservers;
     RegisteredObservers _observers;
 
+    /**
+    \brief Notify all registered ::HistoryObserver that the History has changed.
+    Calls HistoryObserver.update(this) for each registered observer.
+    */
     void notify_change();
 
 		position _front;
@@ -159,6 +312,9 @@ namespace sgpem
      */
     bool  set_notify_enabled(bool enabled = true);
 
+    /**
+     \brief Flag indicating notification to observers enabled/disbled.
+     */
     bool _notify;
 
   }; //~ class History
diff --git a/src/backend/sgpemv2/invalid_plugin_exception.hh b/src/backend/sgpemv2/invalid_plugin_exception.hh
index edb44e6..f06ed4d 100644
--- a/src/backend/sgpemv2/invalid_plugin_exception.hh
+++ b/src/backend/sgpemv2/invalid_plugin_exception.hh
@@ -1,4 +1,4 @@
-// src/backend/invalid_plugin_exception.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/invalid_plugin_exception.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -27,9 +27,18 @@
 
 namespace sgpem
 {
+  /**
+   * \brief This exception is thrown when the DSO you're trying to load doesn't
+   * export a valid SGPEMv2 backend::Plugin interface.
+   */
   class InvalidPluginException : public std::runtime_error
   {
   public:
+    /**
+     * \brief Exception constructor.
+     *
+     * \param what A constant string msg indicating the failure reason.
+     */
     InvalidPluginException(const std::string& what);
   }
   ; //~ class InvalidPluginException
diff --git a/src/backend/sgpemv2/ready_queue.hh b/src/backend/sgpemv2/ready_queue.hh
index 89e51c4..dc0cc45 100644
--- a/src/backend/sgpemv2/ready_queue.hh
+++ b/src/backend/sgpemv2/ready_queue.hh
@@ -1,4 +1,4 @@
-// src/backend/resource.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/ready_queue.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -30,26 +30,75 @@ namespace sgpem
 {
   class ReadyQueue;
   class Thread;
-
   class SG_DLLEXPORT ReadyQueue
   {
   public:
     typedef unsigned int position;
     typedef unsigned int size_t;
 
+  /**
+   * \brief Swaps the object at position \a a with the object
+   * at position \a b Used for implementing in-place sorting algorithms.
+   *
+   * \param a first object position
+   * \param b second object position
+   */
     void       swap(position a, position b) throw (std::out_of_range);
+
+    /**
+     * \brief Return the size of the queue.
+     *
+     * \return _scheds.size()
+     */
     size_t     size() const;
+
+    /**
+     * \brief Returns an item contained in the vector.
+     * Throws an std::out_of_range standard exception
+     * if position is < 1 or > size()-1.
+     *
+     * \return The item at positon \a index.
+     * \throw std::out_of_range if position is < 1 or > size()-1.
+     */
     Thread&    get_item_at(position index) throw (std::out_of_range);
+
+
+    /**
+     * \brief Returns a costant reference to an item contained in the vector.
+     * Throws an std::out_of_range standard exception
+     * if position is < 1 or > size()-1.
+     *
+     * \return A constant reference to the item at positon \a index.
+     * \throw std::out_of_range if position is < 1 or > size()-1
+     */
     const Thread& get_item_at(position index) const throw (std::out_of_range);
+
+    /**
+     * \brief Add a new ::Thread at the end of the queue.
+     *
+     * \param schedulable A reference to the appending thread.
+     */
     void       append(Thread& schedulable);
-    
-		/** \brief Bubble element x to the front of the queue
-		 */
+
+    /**
+     * \brief Bubble element x to the front of the queue
+     */
     void       bubble_to_front(position x) throw(std::out_of_range);
+
+    /**
+     * \brief Remove the first item from the threads vector.
+     */
     void       erase_first();
 
   private:
+    /**
+     * \brief Threads container definition.
+     */
     typedef std::vector<Thread*> Threads;
+
+    /**
+     * \brief Threads container member.
+     */
     Threads _scheds;
   };
 
diff --git a/src/backend/sgpemv2/resource_policies_gatekeeper.hh b/src/backend/sgpemv2/resource_policies_gatekeeper.hh
index 1602748..4a640d0 100644
--- a/src/backend/sgpemv2/resource_policies_gatekeeper.hh
+++ b/src/backend/sgpemv2/resource_policies_gatekeeper.hh
@@ -1,4 +1,4 @@
-// src/backend/resource_policies_gatekeeper.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/resource_policies_gatekeeper.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -53,24 +53,66 @@ namespace sgpem
     typedef ResourcePolicyManager Manager;
     typedef std::vector<Manager*> Managers;
 
+    /**
+     *  \brief Returns registered resources policy managers.
+     *
+     *  \return Registered resources policy managers.
+     */
     const Managers&   get_registered() const;
 
+    /**
+     * \brief Register a new resources policy manager.
+     * A no-op if a manager of the same type already exists.
+     */
     void       register_manager(ResourcePolicyManager* 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 selected policy wasn't managed by it.
+     * If so, the policy should be deactivated before removal, and current_policy reset.
+     *
+     * \param manager The resource policy manager to remove.
+     */
     void       unregister_manager(ResourcePolicyManager* manager);
 
+    /**
+     * \brief Returns the currently active policy.
+     * If no policy was previously activated for the attached ::History,
+     * throws an appropriate exception.
+     *
+     * \return The current policy.
+     */
     ResourcePolicy&   get_current_policy(History* history) throw(std::runtime_error);
-
+    /**
+      \brief Given a policy, sets it as the history current one.
+      Also deactivates the old policy if present, and then activates
+      the new policy before use. If old_policy == new_policy, it's a no-op.
+     */
     void       activate_policy(History* history, ResourcePolicy* policy);
 
   private:
+    /**
+      \brief Private constructor.
+      */
     ResourcePoliciesGatekeeper();     //private constructor.
+    /**
+      \brief Private copy constructor.
+      */
     ResourcePoliciesGatekeeper(const ResourcePoliciesGatekeeper&);
+    /**
+      \brief Private assignment operator.
+      */
     ResourcePoliciesGatekeeper& operator=(const ResourcePoliciesGatekeeper&);
 
     void deactivate_policies(const ResourcePolicyManager& manager);
-
+    /**
+     \brief Container of registered managers.
+     */
     Managers                                _registered;
+    /**
+     \brief Container of active policies.
+     */
     std::map<History*, ResourcePolicy*>     _active_policies;
   };
 
diff --git a/src/backend/sgpemv2/scheduler.hh b/src/backend/sgpemv2/scheduler.hh
index b33da05..181d18e 100644
--- a/src/backend/sgpemv2/scheduler.hh
+++ b/src/backend/sgpemv2/scheduler.hh
@@ -1,4 +1,4 @@
-// src/backend/scheduler.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/scheduler.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
diff --git a/src/backend/sgpemv2/simulation.hh b/src/backend/sgpemv2/simulation.hh
index 5c55bd1..b20a5e6 100644
--- a/src/backend/sgpemv2/simulation.hh
+++ b/src/backend/sgpemv2/simulation.hh
@@ -137,6 +137,10 @@ namespace sgpem
      */
     virtual mode  get_mode() const = 0;
 
+    /** 
+      \return The curent simulation state.
+      \see state
+     */
     virtual state get_state() const = 0;
 
     /**
@@ -148,6 +152,7 @@ namespace sgpem
       \brief Setup the resource policy to be used by the system.
      */
     virtual void set_resource_policy(ResourcePolicy*) = 0;
+
     /**
       \return The CPU policy currently in use.
      */
@@ -158,8 +163,14 @@ namespace sgpem
      */
     virtual ResourcePolicy* get_resource_policy() = 0;
 
+    /**
+      \return A reference to the History associated with this simulation.
+     */
     virtual History& get_history() = 0;
 
+    /**
+      \return A const reference to the History associated with this simulation.
+     */
     virtual const History& get_history() const = 0;
 
     /**
@@ -168,9 +179,18 @@ namespace sgpem
      */
     static Simulation& get_instance();
  
+    /**
+     \brief Tie a new observer to this simulation.
 
-
+     \param observer The observer to attach.
+     */
     virtual void  attach(SimulationObserver& observer);
+
+    /**
+     \brief Removed an attached observer from this simulation.
+
+     \param observer The observer to detach.
+     */
     virtual void  detach(const SimulationObserver& observer);
 
   protected:
diff --git a/src/backend/sgpemv2/user_interrupt_exception.hh b/src/backend/sgpemv2/user_interrupt_exception.hh
index dee77b5..82bb9ec 100644
--- a/src/backend/sgpemv2/user_interrupt_exception.hh
+++ b/src/backend/sgpemv2/user_interrupt_exception.hh
@@ -1,4 +1,4 @@
-// src/backend/user_interrupt_exception.hh - Copyright 2005, 2006, University
+// src/backend/sgpemv2/user_interrupt_exception.hh - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -34,6 +34,10 @@ namespace sgpem
 {
   class UserInterruptException;
 
+  /**
+   \brief This class is thrown by PythonPolicy if the called python
+   policy doesn't return before a timeout expires.
+   */
   class SG_DLLEXPORT UserInterruptException : public CPUPolicyException
   {
   public:
diff --git a/src/backend/string_utils.cc b/src/backend/string_utils.cc
index e52a7f7..52b0513 100644
--- a/src/backend/string_utils.cc
+++ b/src/backend/string_utils.cc
@@ -25,7 +25,6 @@
 #include <sstream>
 
 using namespace std;
-//using namespace sgpem;
 using Glib::ustring;
 
 namespace sgpem
@@ -43,7 +42,16 @@ namespace sgpem
   // Specialized further down in this file:
   // template SG_DLLEXPORT bool string_to<bool>(const Glib::ustring&);
 
-
+  /**
+   * \brief Converts from ustring to a template type.
+   *
+   * NOTE: For the template must be defined an istream
+   * operator >>.
+   *
+   * \param <typename T> The type to convert to.
+   * \param str The string to convert from.
+   * \return A T value converted from str.
+   */
   template <typename T>
   T
   string_to(const ustring& str) throw(domain_error)
@@ -79,7 +87,11 @@ namespace sgpem
     return result;
   }
 
-
+  /**
+   * \brief Specialized string_to to convert from ustring to bool values.
+   * \param str The string to convert from.
+   * \return A bool value converted from str.
+   */
   template <>
   SG_DLLEXPORT bool 
   string_to<bool>(const Glib::ustring& str) throw(domain_error)
@@ -115,8 +127,15 @@ namespace sgpem
     return value;
   }
 
-  /**
-   \brief A function that converts an integer value to an Unicode string
+   /**
+   * \brief A function that converts a template type value to an Unicode string
+   *
+   * NOTE: For the template must be defined an ostream
+   * operator <<.
+   *
+   * \param <typename T> The type to convert from.
+   * \param val the input value to convert.
+   * \param str The string to convert to.
    */
   template<typename T>
   void
diff --git a/src/holt_widget.cc b/src/holt_widget.cc
index c72fbec..87dcbab 100644
--- a/src/holt_widget.cc
+++ b/src/holt_widget.cc
@@ -660,6 +660,7 @@ HoltWidget::acquire()
   std::cout << "HoltWidget::acquire" << endl;
 #endif
 
+  // clear all previous collected items
   const HoltResources& const_holt_resources = _holt_resources;
   for(Iseq<HoltResources::const_iterator> it = iseq(const_holt_resources); it; ++it)
     delete it->second;
@@ -676,19 +677,28 @@ HoltWidget::acquire()
   const History& hist = _simulation->get_history();
   const Environment& env = hist.get_last_environment();
 
+  // arbitrary position (will be changed by arrange())
   Vec2 pos(2*_radius, 2*_radius);
   const Environment::Resources& rvect = env.get_resources();
 
+  // scan all resources making an HolResource object
   Environment::Resources::const_iterator riter = rvect.begin();
   while(riter!=rvect.end())
   {
     resource_key_t index = (*riter).first;
     Resource* r = (*riter).second;
 
+    // create HolResource object and insert it in container
     HoltResource *hr = new HoltResource(*r, index, pos);
     HoltResources::iterator temp = _holt_resources.insert(std::pair<resource_key_t,HoltResource*>(index, hr)).first;
+
+    // count resources
     _n_res++;
+
+    // skip to next
     riter++;
+
+    // calc next position
     pos += Vec2(4*_radius, 0);
   }
   
@@ -702,6 +712,9 @@ HoltWidget::acquire()
     Process* p = (*proc_iter);
     proc_iter++;
 
+    // create a new HoltScedulable per process
+    // if running or ready or blocked and
+    // show threads is disabled
     Schedulable::state proc_state = p->get_state();
     if(proc_state==Schedulable::state_running
       || proc_state==Schedulable::state_ready
@@ -724,11 +737,10 @@ HoltWidget::acquire()
 
         Thread* t = (*thr_iter);
         thr_iter++;
-        /*
-        os << "    thread name: " << t->get_name()
-          << " arrival_time: " << t->get_arrival_time()
-          << " base_priority: " << t->get_base_priority() << endl;
-      */
+
+        // create a new HoltScedulable per process
+        // if running or ready or blocked and
+        // show threads is disabled
         Schedulable::state thr_state = t->get_state();
         if(thr_state==Schedulable::state_running
           || thr_state==Schedulable::state_ready
@@ -759,7 +771,10 @@ HoltWidget::acquire()
 
               SubRequest* sr = (*subr_iter);
               subr_iter++;
-              // os << "        sub request: " /* << " resource_key: " << sr->get_resource_key() */;
+
+              // create a new HoltRequest per subrequest
+              // if unallocable or allocated or allocable
+              // tieing it with current process or thread
               Request::state subr_state = sr->get_state();
               if(subr_state==Request::state_unallocable
                 || subr_state==Request::state_allocated
@@ -777,10 +792,6 @@ HoltWidget::acquire()
                   _holt_requests.push_back(hreq);
                 }
               } // ~ if(subr_state==Request::state_unallocable ... etc
-              /*
-              os << " length: " << sr->get_length();
-              os << " state: " << sr->get_state() << endl;
-            */
             } // ~ while(subr_iter!=srvect.end())
           } // ~ while(req_iter!=rvect.end())
         } // ~ if(thr_state==Schedulable::state_running ...
@@ -789,7 +800,6 @@ HoltWidget::acquire()
 
   }
 
-  // arrange();
 }
 
 
@@ -861,8 +871,13 @@ HoltWidget::calc_drawing_size(cairo_t* ctx, size_t& width, size_t& height)
   cout << "Holt widget BEFORE calc_drawing_size width=" << width << " height=" << height << endl;
 #endif
 
-  // int pos   = _simulation->get_front();
-  // const History& hist = _simulation->get_history();
+  // the disposition of objects take care that:
+  // - an object has a 2.0*_radius diameter
+  // - a space _radius wide is required around objects
+  //
+  // this is the reason because the expression 4 * _radius
+  // recurs many times in the code below
+  //
   int max   = _n_proc;
   if(_n_res>_n_proc)
     max = _n_res;
@@ -875,21 +890,31 @@ HoltWidget::calc_drawing_size(cairo_t* ctx, size_t& width, size_t& height)
   switch(_arrange_mode)
   {
     case arrange_horizontal:
+      // max number of items times the space required by one
       width  = (size_t) (max * 4 * _radius);
+      // aspace of 4 * _radius between rows
       height = (size_t) (10 * _radius);
       break;
 
     case arrange_vertical:
+      // aspace of 4 * _radius between columns
       width  = (size_t) (10 * _radius);
+      // max number of items times the space required by one
       height = (size_t) (max * 4 * _radius);
       break;
 
     case arrange_circular:
+      // lilltle more complex diameter calculation
+      // the circle is divided in tot sectors
       int tot = (_n_proc + _n_res);
+      // each sector is alpha wide
       double alpha = 0;
       if(tot>0)
         alpha = M_PI / tot;
+      // each element is placed on vertex of a tot sides polygon
+      // side length
       double side = 2 * sin(alpha/2);
+      // calc of expected limiting circle diameter
       double diam = 4 * _radius;
       if(side>0)
       {
diff --git a/src/testsuite/test-cairo_widget.cc b/src/testsuite/test-cairo_widget.cc
index 1e3ad61..d04da20 100644
--- a/src/testsuite/test-cairo_widget.cc
+++ b/src/testsuite/test-cairo_widget.cc
@@ -1,4 +1,4 @@
-// src/simulation_widget.hh - Copyright 2005, 2006, University
+// src/testsuite/test-cairo_widget.cc - Copyright 2005, 2006, University
 //               of Padova, dept. of Pure and Applied
 //               Mathematics
 //
@@ -22,7 +22,6 @@
 
 #include "cairo_widget.hh"
 #include "cairo_elements.hh"
-// #include "backend/string_utils.hh"
 #include "gettext.h"
 
 
@@ -61,7 +60,6 @@ namespace sgpem
     void change_scaling_mode();
 
     virtual void calc_drawing_size(cairo_t* ctx, size_t& width, size_t& height);
-    // void calc_size(const History& history, size_t& width, size_t& height) const;
   private:
     int _desired_w;
     int _desired_h;
@@ -155,8 +153,6 @@ TestWidget::draw_widget(cairo_t* ctx)
 void
 TestWidget::calc_drawing_size(cairo_t* ctx, size_t& width, size_t& height)
 {
-  // FIXME: write me
-  // some magic here!
   width  = _desired_w;
   height = _desired_h;
 }