Commenting.

eeschema/tools/ee_selection_tool.h

@@ -74,34 +74,34 @@ public:
     void OnIdle( wxIdleEvent& aEvent );
 
     /**
-     * Return the set of currently selected items.
+     * @return the set of currently selected items.
      */
     EE_SELECTION& GetSelection();
 
     /**
-     * Return either an existing selection (filtered), or the selection at the current
+     * Return either an existing selection (filtered), or the selection at the current cursor
-     * cursor if the existing selection is empty.
+     * position if the existing selection is empty.
      *
-     * @param aScanTypes an optional type filter indicating the legal KICAD_Ts to be returned.
+     * @param aScanTypes [optional] List of item types that are acceptable for selection.
      * @return either the current selection or, if empty, the selection at the cursor.
      */
     EE_SELECTION& RequestSelection( const std::vector<KICAD_T>& aScanTypes = { SCH_LOCATE_ANY_T } );
 
     /**
-     * This overload of SelectPoint will create an EE_COLLECTOR and collect hits at location aWhere
+     * Perform a click-type selection at a point (usually the cursor position).
-     * before calling the primary SelectPoint method.
      *
-     * @param aWhere is the location where the item(s) should be collected
+     * @param aWhere Point from which the selection should be made.
-     * @param aScanTypes is a list of items that are acceptable for collection
+     * @param aScanTypes [optional] List of item types that are acceptable for selection.
-     * @param aItem is set to the newly selected item if only one was selected, otherwise is
+     * @param aItem [out, optional] The newly selected item if only one was selected, otherwise
      *              unchanged.
-     * @param aSelectionCancelledFlag allows the function to inform its caller that a selection
+     * @param aSelectionCancelledFlag [out] Allows the function to inform its caller that a
-     *                                was canceled (for instance, by clicking outside of the
+     *                                selection was canceled (for instance, by clicking outside of
-     *                                disambiguation menu).
+     *                                the disambiguation menu).
-     * @param aCheckLocked indicates if locked items should be excluded.
+     * @param aCheckLocked Indicates if locked items should be excluded.
-     * @param aAdd indicates if found item(s) should be added to the selection
+     * @param aAdd Indicates if found item(s) should be added to the selection.
-     * @param aSubtract indicates if found item(s) should be subtracted from the selection
+     * @param aSubtract Indicates if found item(s) should be subtracted from the selection.
-     * @param aExclusiveOr indicates if found item(s) should be toggle in the selection
+     * @param aExclusiveOr Indicates if found item(s) should be toggle in the selection.
+     * @return true if the selection was modified.
      */
     bool SelectPoint( const VECTOR2I& aWhere,
                       const std::vector<KICAD_T>& aScanTypes = { SCH_LOCATE_ANY_T },
@@ -109,13 +109,24 @@ public:
                       bool aCheckLocked = false, bool aAdd = false, bool aSubtract = false,
                       bool aExclusiveOr = false );
 
-    ///< Find (but don't select) node under cursor
+    /**
+     * Finds a connected item at a point (usually the cursor position).  Iterative process with a
+     * decreasing slop factor.
+     * @param aPosition Cursor position from which the search should be made.
+     * @return a connected item or nullptr.
+     */
     EDA_ITEM* GetNode( VECTOR2I aPosition );
 
-    ///< Select node under cursor
+    /**
+     * Selects the connected item at the current cursor position.  Iterative process with a
+     * decreasing slop factor.
+     */
     int SelectNode( const TOOL_EVENT& aEvent );
 
-    ///< If node selected then expand to connection, otherwise select connection under cursor
+    /**
+     * If a connected item is selected then expand the selection to the entire connection,
+     * otherwise select connection under the current cursor position.
+     */
     int SelectConnection( const TOOL_EVENT& aEvent );
 
     ///< Clear current selection event handler.
@@ -149,14 +160,12 @@ public:
     void RebuildSelection();
 
     /**
-     * Select one or more items at the location given by parameter aWhere.
+     * Collect one or more items at a given point.  This method does not attempt to disambiguate
+     * multiple items and is simply "collecting".
      *
-     * This method does not attempt to disambiguate multiple items and is simply "collecting"
+     * @param aCollector [in, out] Provides collection conditions and stores collected items.
-     *
+     * @param aWhere Point from which the collection should be made.
-     * @param aCollector is the collector object that will store found item(s)
+     * @param aScanTypes [optional] A list of item types that are acceptable for collection.
-     * @param aWhere is the place where the item should be selected.
-     * @param aScanTypes is a list of items that are acceptable for collection
-     * @param aCheckLocked indicates if locked items should be excluded.
      */
     bool CollectHits( EE_COLLECTOR& aCollector, const VECTOR2I& aWhere,
                       const std::vector<KICAD_T>& aScanTypes = { SCH_LOCATE_ANY_T } );
@@ -171,27 +180,26 @@ private:
      * Apply rules to narrow the collection down to selectable objects, and then heuristics
      * to try and narrow it to a single object.
      *
-     * @param collector EE_COLLECTOR with elements to filter
+     * @param aCollector [in, out] Provides collection conditions and stores collected items.
      * @param aWhere point where we should narrow (if relevant)
      * @param aCheckLocked If false, remove locked elements from #collector
      */
     void narrowSelection( EE_COLLECTOR& collector, const VECTOR2I& aWhere, bool aCheckLocked );
 
     /**
-     * This is the primary SelectPoint method that will prompt the user with a menu to disambiguate
+     * Perform a click-type selection at a point (usually the cursor position).
-     * multiple selections and then finish by adding, subtracting or toggling the item(s) to the
-     * actual selection group.
      *
-     * @param aCollector is an EE_COLLECTOR that already has collected items
+     * @param aCollector [in, out] Provides collection conditions and stores collected items.
-     * @param aWhere position of the selected point
+     * @param aWhere Point from which the selection should be made.
-     * @param aItem is set to the newly selected item if only one was selected, otherwise is
+     * @param aItem [out, optional] The newly selected item if only one was selected, otherwise
      *              unchanged.
-     * @param aSelectionCancelledFlag allows the function to inform its caller that a selection
+     * @param aSelectionCancelledFlag [out] Allows the function to inform its caller that a
-     *                                was canceled (for instance, by clicking outside of the
+     *                                selection was canceled (for instance, by clicking outside of
-     *                                disambiguation menu).
+     *                                the disambiguation menu).
-     * @param aAdd indicates if found item(s) should be added to the selection
+     * @param aAdd Indicates if found item(s) should be added to the selection.
-     * @param aSubtract indicates if found item(s) should be subtracted from the selection
+     * @param aSubtract Indicates if found item(s) should be subtracted from the selection.
-     * @param aExclusiveOr indicates if found item(s) should be toggle in the selection
+     * @param aExclusiveOr Indicates if found item(s) should be toggle in the selection.
+     * @return true if the selection was modified.
      */
     bool selectPoint( EE_COLLECTOR& aCollector, const VECTOR2I& aWhere, EDA_ITEM** aItem = nullptr,
                       bool* aSelectionCancelledFlag = nullptr, bool aAdd = false,
@@ -210,34 +218,34 @@ private:
     int disambiguateCursor( const TOOL_EVENT& aEvent );
 
     /**
-     * Take necessary action mark an item as selected.
+     * Take necessary action to mark an item as selected.
      *
-     * @param aItem is an item to be selected.
+     * @param aItem The item to be selected.
      */
     void select( EDA_ITEM* aItem ) override;
 
     /**
-     * Take necessary action mark an item as unselected.
+     * Take necessary action to mark an item as unselected.
      *
-     * @param aItem is an item to be unselected.
+     * @param aItem The item to be unselected.
      */
     void unselect( EDA_ITEM* aItem ) override;
 
     /**
      * Highlight the item visually.
      *
-     * @param aItem is an item to be be highlighted.
+     * @param aItem The item to be highlighted.
-     * @param aHighlightMode should be either SELECTED or BRIGHTENED
+     * @param aHighlightMode Either SELECTED or BRIGHTENED
-     * @param aGroup is the group to add the item to in the BRIGHTENED mode.
+     * @param aGroup [otpional] A group to add the item to.
      */
     void highlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override;
 
     /**
      * Unhighlight the item visually.
      *
-     * @param aItem is an item to be be highlighted.
+     * @param aItem is an item to be highlighted.
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
-     * @param aGroup is the group to remove the item from.
+     * @param aGroup [optional] A group to remove the item from.
      */
     void unhighlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override;
 
@@ -247,7 +255,7 @@ private:
     void updateReferencePoint();
 
     /**
-     * @return True if the given point is contained in any of selected items' bounding box.
+     * @return true if the given point is contained in any of selected items' bounding boxes.
      */
     bool selectionContains( const VECTOR2I& aPoint ) const;
 

pcbnew/tools/pcb_selection_tool.h

@@ -86,17 +86,18 @@ public:
     int Main( const TOOL_EVENT& aEvent );
 
     /**
-     * Return the set of currently selected items.
+     * @return the set of currently selected items.
      */
     PCB_SELECTION& GetSelection();
 
     /**
-     * Return the current selection set, filtered according to aFlags and aClientFilter.
+     * Return the current selection, filtered according to aClientFilter.
      *
      * If the set is empty, performs the legacy-style hover selection.
      *
-     * @param aConfirmLockedItems if true the user will be prompted if they want to drop locked
+     * @param aClientFilter A callback to allow tool- or action-specific filtering.
-     *                            items from the selection or override the locks.
+     * @param aConfirmLockedItems [optional] Signals that the user shall be asked if they want
+     *                            to drop locked items from the selection or override the locks.
      */
     PCB_SELECTION& RequestSelection( CLIENT_SELECTION_FILTER aClientFilter,
                                      bool aConfirmLockedItems = false );
@@ -112,24 +113,21 @@ public:
     int SelectAll( const TOOL_EVENT& aEvent );
 
     /**
-     * Handle finding an item. Does not do the actual searching, is called
+     * Take necessary actions to mark an item as found.
-     * by the find dialog.
      *
-     * @param aItem Item that was found and needs to be handled.
+     * @param aItem The item that was found and needs to be highlighted/focused/etc.
      */
     void FindItem( BOARD_ITEM* aItem );
 
     /**
      * Take necessary action mark an item as selected.
      *
-     * @param aItem is an item to be selected.
+     * @param aItem The item to be selected.
      */
     void select( EDA_ITEM* aItem ) override;
 
     /**
-     * Check conditions for an item to be selected.
+     * @return true if an item fulfills conditions to be selected.
-     *
-     * @return True if the item fulfills conditions to be selected.
      */
     bool Selectable( const BOARD_ITEM* aItem, bool checkVisibilityOnly = false ) const;
 
@@ -137,8 +135,8 @@ public:
      * Try to guess best selection candidates in case multiple items are clicked, by doing
      * some brain-dead heuristics.
      *
-     * @param aCollector is the collector that has a list of items to be queried.
+     * @param aCollector [in, out] The collector that has a list of items to be narrowed.
-     * @param aWhere is the selection point to consider
+     * @param aWhere The selection point to consider.
      */
     void GuessSelectionCandidates( GENERAL_COLLECTOR& aCollector, const VECTOR2I& aWhere ) const;
 
@@ -164,15 +162,21 @@ public:
     ///< Zoom the screen to fit the bounding box for cross probing/selection sync.
     void zoomFitCrossProbeBBox( EDA_RECT bbox );
 
+    /**
+     * Enter the group at the head of the current selection.
+     */
     void EnterGroup();
 
     /**
-     * Leave the currently entered group.
+     * Leave the currently-entered group.
      *
-     * @param aSelectGroup when true will select the group after leaving
+     * @param aSelectGroup [optional] Select the group after leaving.
      */
     void ExitGroup( bool aSelectGroup = false );
 
+    /**
+     * @return the currently-entered group.
+     */
     PCB_GROUP* GetEnteredGroup() { return m_enteredGroup; }
 
     /**
@@ -182,14 +186,19 @@ public:
     void FilterCollectorForHierarchy( GENERAL_COLLECTOR& aCollector, bool aMultiselect ) const;
 
     /**
-     * Check the "allow free pads" setting and if disabled, upgrade any pad selection to the
+     * Check the "allow free pads" setting and if disabled, replace any pads in the collector
-     * selection of its parent footprint.
+     * with their parent footprints.
      */
     void FilterCollectorForFreePads( GENERAL_COLLECTOR& aCollector ) const;
 
+    /**
+     * Drop any PCB_MARKERs from the collector.
+     */
     void FilterCollectorForMarkers( GENERAL_COLLECTOR& aCollector ) const;
 
-    ///< Apply the SELECTION_FILTER_OPTIONS to a collection of items
+    /**
+     * Apply the SELECTION_FITLER_OPTIONS to the collector.
+     */
     void FilterCollectedItems( GENERAL_COLLECTOR& aCollector, bool aMultiSelect );
 
 protected:
@@ -223,7 +232,6 @@ protected:
     SELECTION& selection() override { return m_selection; }
 
 private:
-
     /**
      * Select an item pointed by the parameter \a aWhere.
      *
@@ -235,20 +243,20 @@ private:
      * @param aSelectionCancelledFlag allows the function to inform its caller that a selection
      *                                was canceled (for instance, by clicking outside of the
      *                                disambiguation menu).
-     * @param aClientFilter allows the client to perform tool- or action-specific filtering.
+     * @param aClientFilter a callback to allow tool- or action-specific filtering.
-     * @return True if an item was selected, false otherwise.
+     * @return whether or not the selection is empty.
      */
     bool selectPoint( const VECTOR2I& aWhere, bool aOnDrag = false,
                       bool* aSelectionCancelledFlag = nullptr,
                       CLIENT_SELECTION_FILTER aClientFilter = nullptr );
 
     /**
-     * Select an item under the cursor unless there is something already selected or
+     * Select an item under the cursor unless there is something already selected.
-     * \a aSelectAlways is true.
      *
-     * @param aForceSelect forces to select an item even if there is an item already selected.
+     * @param aForceSelect [optional] Forces an item to be selected even if there is already a
-     * @param aClientFilter allows the client to perform tool- or action-specific filtering.
+     *                     selection.
-     * @return true if eventually there is an item selected, false otherwise.
+     * @param aClientFilter A callback to allow tool- or action-specific filtering.
+     * @return whether or not the selection is empty.
      */
     bool selectCursor( bool aForceSelect = false,
                        CLIENT_SELECTION_FILTER aClientFilter = nullptr );
@@ -266,12 +274,12 @@ private:
     int disambiguateCursor( const TOOL_EVENT& aEvent );
 
     /**
-     * Expand the current track selection to the next boundary (junctions, pads, or all)
+     * Expand the current connected-item selection to the next boundary (junctions, pads, or all)
      */
     int expandConnection( const TOOL_EVENT& aEvent );
 
     /**
-     * Select all copper connections belonging to the same net(s) as the items in the selection
+     * Select all copper connections belonging to the same net(s) as the items in the selection.
      */
     int selectNet( const TOOL_EVENT& aEvent );
 
@@ -293,7 +301,7 @@ private:
     /**
      * Select connected tracks and vias.
      *
-     * @param aStopCondition where to stop selecting more items
+     * @param aStopCondition Indicates where to stop selecting more items.
      */
     void selectAllConnectedTracks( const std::vector<BOARD_CONNECTED_ITEM*>& aStartItems,
                                    STOP_CONDITION aStopCondition );
@@ -347,26 +355,29 @@ private:
     /**
      * Highlight the item visually.
      *
-     * @param aItem is an item to be be highlighted.
+     * @param aItem The item to be highlighted.
-     * @param aHighlightMode should be either SELECTED or BRIGHTENED
+     * @param aHighlightMode Either SELECTED or BRIGHTENED
-     * @param aGroup is the group to add the item to in the BRIGHTENED mode.
+     * @param aGroup [optional A group to add the item to.
      */
     void highlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override;
 
     /**
      * Unhighlight the item visually.
      *
-     * @param aItem is an item to be be highlighted.
+     * @param aItem The item to be highlighted.
-     * @param aHighlightMode should be either SELECTED or BRIGHTENED
+     * @param aHighlightMode Either SELECTED or BRIGHTENED
-     * @param aGroup is the group to remove the item from.
+     * @param aGroup [optional] A group to remove the item from.
      */
     void unhighlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override;
 
     /**
-     * @return True if the given point is contained in any of selected items' bounding box.
+     * @return true if the given point is contained in any of selected items' bounding boxes.
      */
     bool selectionContains( const VECTOR2I& aPoint ) const;
 
+    /**
+     * @return the distance from \a wWhere to \a aItem, up to and including \a aMaxDistance.
+     */
     int hitTestDistance( const wxPoint& aWhere, BOARD_ITEM* aItem, int aMaxDistance ) const;
 
     /**