Improve some comments.

common/rc_item.h

@@ -48,18 +48,14 @@ public:
 
     /**
      * Function GetItem
-     * retrieves a RC_ITEM by pointer.  The actual item remains owned by the
+     * retrieves a RC_ITEM by index.
-     * list container.
-     * @param aIndex The 0 based index into the list of the desired item.
-     * @return const RC_ITEM* - the desired item or NULL if aIndex is out of range.
      */
     virtual RC_ITEM* GetItem( int aIndex ) = 0;
 
     /**
-     * Function DeleteItems
+     * Function DeleteItem
-     * removes and deletes desired item from the list.
+     * removes (and optionally deletes) the indexed item from the list.
-     * @param aIndex The 0 based index into the list of the desired item which is to be deleted.
+     * @param aDeep If true, the source item should be deleted as well as its entry in the list.
-     * @param aDeep If true, the source item should be deleted as well as the filtered item.
      */
     virtual void DeleteItem( int aIndex, bool aDeep ) = 0;
 
@@ -241,7 +237,8 @@ public:
     /**
      * Function SetAuxiliaryData
      * initialize data for the second (auxiliary) item
-     * @param aAuxiliaryText = the second text (main text) concerning the second schematic or board item
+     * @param aAuxiliaryText = the second text (main text) concerning the second schematic
+     *                         or board item
      * @param aAuxiliaryPos = position the second item
      */
     void SetAuxiliaryData( const wxString& aAuxiliaryText, const wxPoint& aAuxiliaryPos )

include/tools_holder.h

@@ -35,6 +35,13 @@ class TOOL_DISPATCHER;
 class ACTIONS;
 
 
+/*
+ * Class TOOLS_HOLDER
+ * A mix-in class which allows its owner to hold a set of tools from the tool framework.
+ *
+ * This is just the framework; the owner is responsible for registering individual tools,
+ * creating the dispatcher, etc.
+ */
 class TOOLS_HOLDER
 {
 protected:
@@ -42,14 +49,17 @@ protected:
     ACTIONS*          m_actions;
     TOOL_DISPATCHER*  m_toolDispatcher;
 
-    std::vector<std::string> m_toolStack;   // Stack of user-level "tools".  Not to be confused
+    std::vector<std::string> m_toolStack;   // Stack of user-level "tools".  This is NOT a
-                                            // with a stack of TOOL_BASE instances, because many
+                                            // stack of TOOL instances, because somewhat
-                                            // of them implement multiple user-level "tools".  The
+                                            // confusingly most TOOLs implement more than one
-                                            // user-level "tools" equate to ACTIONs.
+                                            // user-level tool.  A user-level tool actually
+                                            // equates to an ACTION handler, so this stack
+                                            // stores ACTION names.
 
-    bool              m_immediateActions;   // Preference for immediate actions.  If false, the
+    bool              m_immediateActions;   // Preference for immediate actions.  If false,
-                                            // first invocation of a hotkey will just select the
+                                            // the first invocation of a hotkey will just
-                                            // relevant tool.
+                                            // select the relevant tool rather than executing
+                                            // the tool's action.
     bool              m_dragSelects;        // Prefer selection to dragging.
     bool              m_moveWarpsCursor;    // cursor is warped to move/drag origin