From a1d62e0622d13ada7f7c2630999ef303540d71ae Mon Sep 17 00:00:00 2001
From: Jeff Young <jeff@rokeby.ie>
Date: Sun, 29 Mar 2020 20:02:23 +0100
Subject: [PATCH] Improve some comments.

---
 common/rc_item.h       | 15 ++++++---------
 include/tools_holder.h | 24 +++++++++++++++++-------
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/common/rc_item.h b/common/rc_item.h
index 208e7dca7d..31f01ba247 100644
--- a/common/rc_item.h
+++ b/common/rc_item.h
@@ -48,18 +48,14 @@ public:
 
     /**
      * Function GetItem
-     * retrieves a RC_ITEM by pointer.  The actual item remains owned by the
-     * 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.
+     * retrieves a RC_ITEM by index.
      */
     virtual RC_ITEM* GetItem( int aIndex ) = 0;
 
     /**
-     * Function DeleteItems
-     * removes and deletes desired 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 the filtered item.
+     * Function DeleteItem
+     * removes (and optionally deletes) the indexed item from the list.
+     * @param aDeep If true, the source item should be deleted as well as its entry in the list.
      */
     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 )
diff --git a/include/tools_holder.h b/include/tools_holder.h
index b5360b554b..c112d4a997 100644
--- a/include/tools_holder.h
+++ b/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
-                                            // with a stack of TOOL_BASE instances, because many
-                                            // of them implement multiple user-level "tools".  The
-                                            // user-level "tools" equate to ACTIONs.
+    std::vector<std::string> m_toolStack;   // Stack of user-level "tools".  This is NOT a
+                                            // stack of TOOL instances, because somewhat
+                                            // confusingly most TOOLs implement more than one
+                                            // 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
-                                            // first invocation of a hotkey will just select the
-                                            // relevant tool.
+    bool              m_immediateActions;   // Preference for immediate actions.  If false,
+                                            // the first invocation of a hotkey will just
+                                            // 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