Fix the last of broken Doxygen comment specifiers.

eeschema/sim/ngspice.h

@@ -61,7 +61,7 @@ public:
     ///< @copydoc SPICE_SIMULATOR::GetXAxis()
     std::string GetXAxis( SIM_TYPE aType ) const override;
 
-    ///> @copydoc SPICE_SIMULATOR::AllPlots()
+    ///< @copydoc SPICE_SIMULATOR::AllPlots()
     std::vector<std::string> AllPlots() const override;
 
     ///< @copydoc SPICE_SIMULATOR::GetPlot()

eeschema/sim/sim_plot_panel.h

@@ -298,7 +298,7 @@ private:
     ///< @return a new color from the palette
     wxColour generateColor();
 
-    ///> @brief Constructs the plot axes for DC simulation plot
+    ///< @brief Construct the plot axes for DC simulation plot.
     void prepareDCAxes();
 
     // Color index to get a new color from the palette

kicad/tools/kicad_manager_actions.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -32,9 +32,7 @@
 class TOOL_EVENT;
 class TOOL_MANAGER;
 
-/**
+
- * KICAD_MANAGER_ACTIONS
- * */
 class KICAD_MANAGER_ACTIONS : public ACTIONS
 {
 public:
@@ -56,7 +54,7 @@ public:
     static TOOL_ACTION editOtherSch;
     static TOOL_ACTION editOtherPCB;
 
-    ///> @copydoc COMMON_ACTIONS::TranslateLegacyId()
+    ///< @copydoc COMMON_ACTIONS::TranslateLegacyId()
     virtual OPT<TOOL_EVENT> TranslateLegacyId( int aId ) override
     {
         return OPT<TOOL_EVENT>();
@@ -64,5 +62,4 @@ public:
 };
 
 
-
 #endif

kicad/tools/kicad_manager_control.cpp

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -33,7 +33,8 @@
 #include <gestfich.h>
 #include <wx/dir.h>
 
-///> Helper widget to select whether a new directory should be created for a project
+
+///< Helper widget to select whether a new directory should be created for a project.
 class DIR_CHECKBOX : public wxPanel
 {
 public:
@@ -94,8 +95,7 @@ int KICAD_MANAGER_CONTROL::NewProject( const TOOL_EVENT& aEvent )
 
     // wxFileName automatically extracts an extension.  But if it isn't
     // a .pro extension, we should keep it as part of the filename
-    if( !pro.GetExt().IsEmpty()
+    if( !pro.GetExt().IsEmpty() && pro.GetExt().ToStdString() != ProjectFileExtension )
-        && pro.GetExt().ToStdString() != ProjectFileExtension )
         pro.SetName( pro.GetName() + wxT( "." ) + pro.GetExt() );
 
     pro.SetExt( ProjectFileExtension );     // enforce extension
@@ -322,17 +322,6 @@ int KICAD_MANAGER_CONTROL::CloseProject( const TOOL_EVENT& aEvent )
 
 class SAVE_AS_TRAVERSER : public wxDirTraverser
 {
-private:
-    KICAD_MANAGER_FRAME* m_frame;
-
-    wxString             m_projectDirPath;
-    wxString             m_projectName;
-    wxString             m_newProjectDirPath;
-    wxString             m_newProjectName;
-
-    wxFileName           m_newProjectFile;
-    wxString             m_errors;
-
 public:
     SAVE_AS_TRAVERSER( KICAD_MANAGER_FRAME* aFrame,
                        const wxString& aSrcProjectDirPath,
@@ -487,6 +476,17 @@ public:
     wxString GetErrors() { return m_errors; }
 
     wxFileName GetNewProjectFile() { return m_newProjectFile; }
+
+private:
+    KICAD_MANAGER_FRAME* m_frame;
+
+    wxString             m_projectDirPath;
+    wxString             m_projectName;
+    wxString             m_newProjectDirPath;
+    wxString             m_newProjectName;
+
+    wxFileName           m_newProjectFile;
+    wxString             m_errors;
 };
 
 
@@ -648,7 +648,7 @@ int KICAD_MANAGER_CONTROL::ShowPlayer( const TOOL_EVENT& aEvent )
         // Show the frame (and update widgets to set valid sizes),
         // after creating player and before calling OpenProjectFiles().
         // Useful because loading a complex board and building its internal data can be
-        // time consumming
+        // time consuming
         player->Show( true );
         wxSafeYield();
 
@@ -676,9 +676,6 @@ int KICAD_MANAGER_CONTROL::ShowPlayer( const TOOL_EVENT& aEvent )
 
 class TERMINATE_HANDLER : public wxProcess
 {
-private:
-    wxString m_appName;
-
 public:
     TERMINATE_HANDLER( const wxString& appName ) :
             m_appName( appName )
@@ -686,9 +683,7 @@ public:
 
     void OnTerminate( int pid, int status ) override
     {
-        wxString msg = wxString::Format( _( "%s closed [pid=%d]\n" ),
+        wxString msg = wxString::Format( _( "%s closed [pid=%d]\n" ), m_appName, pid );
-                                         m_appName,
-                                         pid );
 
         wxWindow* window = wxWindow::FindWindowByName( KICAD_MANAGER_FRAME_NAME );
 
@@ -704,6 +699,9 @@ public:
 
         delete this;
     }
+
+private:
+    wxString m_appName;
 };
 
 
@@ -734,7 +732,8 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent )
 
     if( aEvent.Parameter<wxString*>() )
         params = *aEvent.Parameter<wxString*>();
-    else if( ( aEvent.IsAction( &KICAD_MANAGER_ACTIONS::viewGerbers ) ) && m_frame->IsProjectActive() )
+    else if( ( aEvent.IsAction( &KICAD_MANAGER_ACTIONS::viewGerbers ) )
+           && m_frame->IsProjectActive() )
         params = m_frame->Prj().GetProjectPath();
 
     if( !params.empty() )
@@ -746,10 +745,7 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent )
 
     if( pid > 0 )
     {
-        wxString msg = wxString::Format( _( "%s %s opened [pid=%ld]\n" ),
+        wxString msg = wxString::Format( _( "%s %s opened [pid=%ld]\n" ), execFile, params, pid );
-                                         execFile,
-                                         params,
-                                         pid );
         m_frame->PrintMsg( msg );
 
 #ifdef __WXMAC__
@@ -769,7 +765,8 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent )
 void KICAD_MANAGER_CONTROL::setTransitions()
 {
     Go( &KICAD_MANAGER_CONTROL::NewProject,      KICAD_MANAGER_ACTIONS::newProject.MakeEvent() );
-    Go( &KICAD_MANAGER_CONTROL::NewFromTemplate, KICAD_MANAGER_ACTIONS::newFromTemplate.MakeEvent() );
+    Go( &KICAD_MANAGER_CONTROL::NewFromTemplate,
+        KICAD_MANAGER_ACTIONS::newFromTemplate.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::OpenProject,     KICAD_MANAGER_ACTIONS::openProject.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::CloseProject,    KICAD_MANAGER_ACTIONS::closeProject.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::SaveProjectAs,   ACTIONS::saveAs.MakeEvent() );
@@ -780,12 +777,15 @@ void KICAD_MANAGER_CONTROL::setTransitions()
     Go( &KICAD_MANAGER_CONTROL::ShowPlayer,      KICAD_MANAGER_ACTIONS::editSchematic.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::ShowPlayer,      KICAD_MANAGER_ACTIONS::editSymbols.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::ShowPlayer,      KICAD_MANAGER_ACTIONS::editPCB.MakeEvent() );
-    Go( &KICAD_MANAGER_CONTROL::ShowPlayer,      KICAD_MANAGER_ACTIONS::editFootprints.MakeEvent() );
+    Go( &KICAD_MANAGER_CONTROL::ShowPlayer,
+        KICAD_MANAGER_ACTIONS::editFootprints.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::viewGerbers.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::convertImage.MakeEvent() );
-    Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::showCalculator.MakeEvent() );
+    Go( &KICAD_MANAGER_CONTROL::Execute,
+        KICAD_MANAGER_ACTIONS::showCalculator.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::editWorksheet.MakeEvent() );
-    Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::openTextEditor.MakeEvent() );
+    Go( &KICAD_MANAGER_CONTROL::Execute,
+        KICAD_MANAGER_ACTIONS::openTextEditor.MakeEvent() );
 
     Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::editOtherSch.MakeEvent() );
     Go( &KICAD_MANAGER_CONTROL::Execute,         KICAD_MANAGER_ACTIONS::editOtherPCB.MakeEvent() );

kicad/tools/kicad_manager_control.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -33,11 +33,8 @@ class KICAD_MANAGER_FRAME;
 
 
 /**
- * KICAD_MANAGER_CONTROL
+ * Handle actions in the kicad manager frame.
- *
- * Handles actions in the kicad manager frame.
  */
-
 class KICAD_MANAGER_CONTROL : public TOOL_INTERACTIVE
 {
 public:
@@ -59,11 +56,11 @@ public:
     int ShowPlayer( const TOOL_EVENT& aEvent );
     int Execute( const TOOL_EVENT& aEvent );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:
-    ///> Pointer to the currently used edit/draw frame.
+    ///< Pointer to the currently used edit/draw frame.
     KICAD_MANAGER_FRAME* m_frame;
 
     // Mutex to allow only a single KiFace to load at one time (released when loaded)

pagelayout_editor/pl_draw_panel_gal.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -38,7 +38,7 @@ public:
 
     virtual ~PL_DRAW_PANEL_GAL();
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo()
     void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
 
     /**
@@ -46,17 +46,17 @@ public:
      */
     void DisplayWorksheet();
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::SwitchBackend
+    ///< @copydoc EDA_DRAW_PANEL_GAL::SwitchBackend
     bool SwitchBackend( GAL_TYPE aGalType ) override;
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer
+    ///< @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer
     virtual void SetTopLayer( int aLayer ) override;
 
 protected:
-    ///> Sets rendering targets & dependencies for layers.
+    ///< Set rendering targets & dependencies for layers.
     void setDefaultLayerDeps();
 
-    ///> Currently used worksheet
+    ///< Currently used worksheet
     std::unique_ptr<KIGFX::WS_PROXY_VIEW_ITEM> m_worksheet;
 
     std::unique_ptr<WS_DRAW_ITEM_PAGE> m_pageDrawItem;

pagelayout_editor/tools/pl_actions.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -33,9 +33,7 @@ class TOOL_EVENT;
 class TOOL_MANAGER;
 
 /**
- * PL_ACTIONS
+ * Gather all the actions that are shared by tools. The instance of PL_ACTIONS is created
- *
- * Gathers all the actions that are shared by tools. The instance of PL_ACTIONS is created
  * inside of ACTION_MANAGER object that registers the actions.
  */
 class PL_ACTIONS : public ACTIONS
@@ -45,18 +43,18 @@ public:
     /// Activation of the selection tool
     static TOOL_ACTION selectionActivate;
 
-    /// Clears the current selection
+    /// Clear the current selection
     static TOOL_ACTION clearSelection;
 
-    /// Selects an item (specified as the event parameter).
+    /// Select an item (specified as the event parameter).
     static TOOL_ACTION addItemToSel;
     static TOOL_ACTION removeItemFromSel;
 
-    /// Selects a list of items (specified as the event parameter)
+    /// Select a list of items (specified as the event parameter)
     static TOOL_ACTION addItemsToSel;
     static TOOL_ACTION removeItemsFromSel;
 
-    /// Runs a selection menu to select from a list of items
+    /// Run a selection menu to select from a list of items
     static TOOL_ACTION selectionMenu;
 
     // Tools
@@ -78,7 +76,7 @@ public:
     static TOOL_ACTION showInspector;
     static TOOL_ACTION previewSettings;
 
-    ///> @copydoc COMMON_ACTIONS::TranslateLegacyId()
+    ///< @copydoc COMMON_ACTIONS::TranslateLegacyId()
     virtual OPT<TOOL_EVENT> TranslateLegacyId( int aId ) override { return OPT<TOOL_EVENT>(); }
 };
 

pagelayout_editor/tools/pl_drawing_tools.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -34,8 +34,6 @@ class PL_SELECTION_TOOL;
 
 
 /**
- * PL_DRAWING_TOOLS
- *
  * Tool responsible for drawing/placing items (lines, rectangles, text, etc.)
  */
 
@@ -55,7 +53,7 @@ public:
     int PlaceItem( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:

pagelayout_editor/tools/pl_edit_tool.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -58,37 +58,35 @@ public:
     int ImportWorksheetContent( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DoDelete()
+     * Delete the selected items, or the item under the cursor.
-     *
-     * Deletes the selected items, or the item under the cursor.
      */
     int DoDelete( const TOOL_EVENT& aEvent );
 
-    ///> Runs the deletion tool.
+    ///< Run the deletion tool.
     int DeleteItemCursor( const TOOL_EVENT& aEvent );
 
 private:
     void moveItem( WS_DATA_ITEM* aItem, VECTOR2I aDelta );
 
-    ///> Returns the right modification point (e.g. for rotation), depending on the number of
+    ///< Return the right modification point (e.g. for rotation), depending on the number of
-    ///> selected items.
+    ///< selected items.
     bool updateModificationPoint( PL_SELECTION& aSelection );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:
     PL_EDITOR_FRAME*   m_frame;
     PL_SELECTION_TOOL* m_selectionTool;
 
-    ///> Flag determining if anything is being dragged right now
+    ///< Flag determining if anything is being dragged right now.
     bool               m_moveInProgress;
 
-    ///> Used for chaining commands
+    ///< Used for chaining commands.
     VECTOR2I           m_moveOffset;
 
-    ///> Last cursor position (needed for getModificationPoint() to avoid changes
+    ///< Last cursor position (needed for getModificationPoint() to avoid changes
-    ///> of edit reference point).
+    ///< of edit reference point).
     VECTOR2I           m_cursor;
 
     EDA_ITEM*          m_pickerItem;

pagelayout_editor/tools/pl_editor_control.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -32,9 +32,7 @@ class PL_EDITOR_FRAME;
 
 
 /**
- * PL_EDITOR_CONTROL
+ * Handle actions specific to the page layout editor.
- *
- * Handles actions specific to the schematic editor in eeschema.
  */
 class PL_EDITOR_CONTROL : public wxEvtHandler, public TOOL_INTERACTIVE
 {
@@ -70,7 +68,7 @@ public:
     int UpdateMessagePanel( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:

pagelayout_editor/tools/pl_point_editor.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -34,8 +34,6 @@ class PL_SELECTION_TOOL;
 class PL_EDITOR_FRAME;
 
 /**
- * PL_POINT_EDITOR
- *
  * Tool that displays edit points allowing to modify items by dragging the points.
  */
 class PL_POINT_EDITOR : public TOOL_INTERACTIVE
@@ -52,28 +50,28 @@ public:
     int Main( const TOOL_EVENT& aEvent );
 
     /**
-     * Indicates the cursor is over an edit point.  Used to coordinate cursor shapes with
+     * Indicate the cursor is over an edit point.  Used to coordinate cursor shapes with
      * other tools.
      */
     bool HasPoint() { return m_editedPoint != nullptr; }
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:
-    ///> Updates item's points with edit points.
+    ///< Update item's points with edit points.
     void updateItem() const;
 
-    ///> Updates edit points with item's points.
+    ///< Update edit points with item's points.
     void updatePoints();
 
-    ///> Updates which point is being edited.
+    ///< Update which point is being edited.
     void updateEditedPoint( const TOOL_EVENT& aEvent );
 
-    ///> Sets the current point being edited. NULL means none.
+    ///< Set the current point being edited. NULL means none.
     void setEditedPoint( EDIT_POINT* aPoint );
 
-    ///> Returns true if aPoint is the currently modified point.
+    ///< Return true if aPoint is the currently modified point.
     inline bool isModified( const EDIT_POINT& aPoint ) const
     {
         return m_editedPoint == &aPoint;
@@ -96,10 +94,10 @@ private:
     PL_EDITOR_FRAME*             m_frame;
     PL_SELECTION_TOOL*           m_selectionTool;
 
-    ///> Currently edited point, NULL if there is none.
+    ///< Currently edited point, NULL if there is none.
     EDIT_POINT*                  m_editedPoint;
 
-    ///> Currently available edit points.
+    ///< Currently available edit points.
     std::shared_ptr<EDIT_POINTS> m_editPoints;
 };
 

pagelayout_editor/tools/pl_selection_tool.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -54,35 +54,29 @@ public:
     int UpdateMenu( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Main()
-     *
      * The main loop.
      */
     int Main( const TOOL_EVENT& aEvent );
 
     /**
-     * Function GetSelection()
+     * Return the set of currently selected items.
-     *
-     * Returns the set of currently selected items.
      */
     PL_SELECTION& GetSelection();
 
     /**
-     * Function RequestSelection()
+     * Return either an existing selection (filtered), or the selection at the current
-     *
-     * Returns either an existing selection (filtered), or the selection at the current
      * cursor if the existing selection is empty.
      */
     PL_SELECTION& RequestSelection();
 
     /**
-     * Function selectPoint()
+     * Select an item pointed by the parameter aWhere. If there is more than one item at that
-     * Selects an item pointed by the parameter aWhere. If there is more than one item at that
      * place, there is a menu displayed that allows one to choose the item.
      *
      * @param aWhere is the place where the item should be selected.
      * @param aSelectionCancelledFlag allows the function to inform its caller that a selection
-     * was cancelled (for instance, by clicking outside of the disambiguation menu).
+     *                                was canceled (for instance, by clicking outside of the
+     *                                disambiguation menu).
      */
     void SelectPoint( const VECTOR2I& aWhere, bool* aSelectionCancelledFlag = nullptr );
 
@@ -109,21 +103,18 @@ public:
     void RebuildSelection();
 
     /**
-     * Function SelectionMenu()
      * Shows a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single
      * item.
      *
-     * NOTE: this routine DOES NOT modify the selection.
+     * @note This routine **does not** modify the selection.
      */
     int SelectionMenu( const TOOL_EVENT& aEvent );
 
 private:
     /**
-     * Function selectMultiple()
+     * Handle drawing a selection box that allows one to select many items at the same time.
-     * Handles drawing a selection box that allows one to select many items at
-     * the same time.
      *
-     * @return true if the function was cancelled (i.e. CancelEvent was received).
+     * @return true if the function was canceled (i.e. CancelEvent was received).
      */
     bool selectMultiple();
 
@@ -134,15 +125,15 @@ private:
     void guessSelectionCandidates( COLLECTOR& collector, const VECTOR2I& aWhere );
 
     /**
-     * Allows the selection of a single item from a list via pop-up menu.  The items are
+     * Allow the selection of a single item from a list via pop-up menu.  The items are
      * highlighted on the canvas when hovered in the menu.  The collector is trimmed to
      * the picked item.
-     * @return true if an item was picked
+     *
+     * @return true if an item was picked.
      */
     bool doSelectionMenu( COLLECTOR* aItems );
 
     /**
-     * Function select()
      * Takes necessary action mark an item as selected.
      *
      * @param aItem is an item to be selected.
@@ -150,16 +141,15 @@ private:
     void select( EDA_ITEM* aItem );
 
     /**
-     * Function unselect()
+     * Take necessary action mark an item as unselected.
-     * Takes necessary action mark an item as unselected.
      *
      * @param aItem is an item to be unselected.
      */
     void unselect( EDA_ITEM* aItem );
 
     /**
-     * Function highlight()
+     * Highlight the item visually.
-     * Highlights the item visually.
+     *
      * @param aItem is an item to be be highlighted.
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
      * @param aGroup is the group to add the item to in the BRIGHTENED mode.
@@ -167,8 +157,8 @@ private:
     void highlight( EDA_ITEM* aItem, int aHighlightMode, PL_SELECTION* aGroup = nullptr );
 
     /**
-     * Function unhighlight()
+     * Unhighlight the item visually.
-     * Unhighlights the item visually.
+     *
      * @param aItem is an item to be be highlighted.
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
      * @param aGroup is the group to remove the item from.
@@ -176,12 +166,11 @@ private:
     void unhighlight( EDA_ITEM* aItem, int aHighlightMode, PL_SELECTION* aGroup = nullptr );
 
     /**
-     * Function selectionContains()
      * @return True if the given point is contained in any of selected items' bounding box.
      */
     bool selectionContains( const VECTOR2I& aPoint ) const;
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:

pcbnew/autorouter/autoplace_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -28,8 +28,6 @@
 
 
 /**
- * AUTOPLACE_TOOL
- *
  * Tool responsible for automagic placement of components.
  */
 class AUTOPLACE_TOOL : public PCB_TOOL_BASE
@@ -38,7 +36,7 @@ public:
     AUTOPLACE_TOOL();
     ~AUTOPLACE_TOOL();
 
-    ///> Bind handlers to corresponding TOOL_ACTIONs
+    ///< Bind handlers to corresponding TOOL_ACTIONs.
     void setTransitions() override;
 
 private:

pcbnew/board_connected_item.h

@@ -3,7 +3,7 @@
  *
  * Copyright (C) 2012 Jean-Pierre Charras, jean-pierre.charras@ujf-grenoble.fr
  * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
- * Copyright (C) 1992-2012 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -35,11 +35,8 @@ class TRACK;
 class PAD;
 
 /**
- * BOARD_CONNECTED_ITEM
+ * A base class derived from #BOARD_ITEM for items that can be connected and have a net, a
- * is a base class derived from BOARD_ITEM for items that can be connected
+ * netname, a clearance ...
- * and have a net, a netname, a clearance ...
- * mainly: tracks, pads and zones
- * Handle connection info
  */
 class BOARD_CONNECTED_ITEM : public BOARD_ITEM
 {
@@ -68,15 +65,14 @@ public:
         }
     }
 
-    ///> @copydoc BOARD_ITEM::IsConnected()
+    ///< @copydoc BOARD_ITEM::IsConnected()
     bool IsConnected() const override
     {
         return true;
     }
 
     /**
-     * Function GetNet
+     * Return #NET_INFO object for a given item.
-     * Returns NET_INFO object for a given item.
      */
     NETINFO_ITEM* GetNet() const
     {
@@ -84,8 +80,7 @@ public:
     }
 
     /**
-     * Function SetNet
+     * Set a NET_INFO object for the item.
-     * Sets a NET_INFO object for the item.
      */
     void SetNet( NETINFO_ITEM* aNetInfo )
     {
@@ -93,8 +88,7 @@ public:
     }
 
     /**
-     * Function GetNetCode
+     * @return the net code.
-     * @return int - the net code.
      */
     int GetNetCode() const
     {
@@ -102,13 +96,15 @@ public:
     }
 
     /**
-     * Sets net using a net code.
+     * Set net using a net code.
-     * @param aNetCode is a net code for the new net. It has to exist in NETINFO_LIST held by BOARD.
+     *
-     * @param aNoAssert if true, do not assert that the net exists.
+     * @note Pads not on copper layers will have their net code always set to 0 (not connected).
-     * Otherwise, item is assigned to the unconnected net.
+     *
+     * @param aNetCode is a net code for the new net. It has to exist in #NETINFO_LIST held
+     *                 by #BOARD.
+     * @param aNoAssert if true, do not assert that the net exists.  Otherwise, item is assigned
+     *                  to the unconnected net.
      * @return true on success, false if the net did not exist
-     * Note also items (in fact pads) not on copper layers will have
-     * their net code always set to 0 (not connected)
      */
     bool SetNetCode( int aNetCode, bool aNoAssert );
 
@@ -118,8 +114,7 @@ public:
     }
 
     /**
-     * Function GetNetname
+     * @return the full netname.
-     * @return wxString - the full netname
      */
     wxString GetNetname() const
     {
@@ -127,15 +122,13 @@ public:
     }
 
     /**
-     * Function GetNetnameMsg
+     * @return the full netname or "<no net>" in square braces, followed by "(Not Found)" if the
-     * @return wxString - the full netname or "<no net>" in square braces, followed by
+     *         netcode is undefined.
-     * "(Not Found)" if the netcode is undefined.
      */
     wxString GetNetnameMsg() const;
 
     /**
-     * Function GetShortNetname
+     * @return the short netname.
-     * @return wxString - the short netname
      */
     wxString GetShortNetname() const
     {
@@ -143,56 +136,54 @@ public:
     }
 
     /**
-     * Function GetClearance
+     * Return an item's "own" clearance in internal units.
-     * returns an item's "own" clearance in internal units.
+     *
-     * @param aLayer the layer in question
+     * @param aLayer the layer in question.
-     * @param aSource [out] optionally reports the source as a user-readable string
+     * @param aSource [out] optionally reports the source as a user-readable string.
-     * @return int - the clearance in internal units.
+     * @return the clearance in internal units.
      */
     virtual int GetOwnClearance( PCB_LAYER_ID aLayer, wxString* aSource = nullptr ) const;
 
     /**
-     * Function GetLocalClearanceOverrides
+     * Return any local clearance overrides set in the "classic" (ie: pre-rule) system.
-     * returns any local clearance overrides set in the "classic" (ie: pre-rule) system.
+     *
-     * @param aSource [out] optionally reports the source as a user-readable string
+     * @param aSource [out] optionally reports the source as a user-readable string.
-     * @return int - the clearance in internal units.
+     * @return the clearance in internal units.
      */
     virtual int GetLocalClearanceOverrides( wxString* aSource ) const { return 0; }
 
     /**
-     * Function GetLocalClearance
+     * Return any local clearances set in the "classic" (ie: pre-rule) system.  These are
-     * returns any local clearances set in the "classic" (ie: pre-rule) system.  These are
+     * things like zone clearance which are **not** an override.
-     * things like zone clearance which are NOT an override.
+     *
-     * @param aSource [out] optionally reports the source as a user-readable string
+     * @param aSource [out] optionally reports the source as a user readable string.
-     * @return int - the clearance in internal units.
+     * @return the clearance in internal units.
      */
     virtual int GetLocalClearance( wxString* aSource ) const { return 0; }
 
     /**
-     * Function GetNetClassPtr
+     * Return the #NETCLASS for this item.
-     * returns the NETCLASS for this item.
      *
-     * Note: do NOT return a std::shared_ptr from this.  It is used heavily in DRC, and the
+     * @note Do **not** return a std::shared_ptr from this.  It is used heavily in DRC, and the
      *       std::shared_ptr stuff shows up large in performance profiling.
      */
     virtual NETCLASS* GetNetClass() const;
 
     /**
-     * Function GetEffectiveNetclass
+     * Return the NETCLASS for this item, or the default netclass if none is defined.
-     * returns the NETCLASS for this item, or the default netclass if none is defined.
      *
-     * Note: do NOT return a std::shared_ptr from this.  It is used heavily in DRC, and the
+     * @note Do **not** return a std::shared_ptr from this.  It is used heavily in DRC, and the
      *       std::shared_ptr stuff shows up large in performance profiling.
      */
     virtual NETCLASS* GetEffectiveNetclass() const;
 
     /**
-     * Function GetNetClassName
+     * Returns the netclass of the zone.
-     * returns a pointer to the netclass of the zone.
+     *
-     * If the net is not found (can happen when a netlist is reread,
+     * If the net is not found (can happen when a netlist is reread) and the net name does not
-     * and the net name does not exist, return the default net class
+     * exist, return the default net class (should not return a null pointer).
-     * (should not return a null pointer).
+     *
-     * @return the Net Class name of this item
+     * @return the net class name of this item.
      */
     virtual wxString GetNetClassName() const;
 
@@ -207,11 +198,10 @@ public:
     }
 
 protected:
-    /// Stores all informations about the net that item belongs to
+    /// Store all information about the net that item belongs to.
     NETINFO_ITEM* m_netinfo;
 
 private:
-
     bool m_localRatsnestVisible;
 };
 

pcbnew/board_stackup_manager/dielectric_material.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 Jean-Pierre Charras, jp.charras at wanadoo.fr
- * Copyright (C) 2009-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2009-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -33,7 +33,7 @@
 #include <wx/string.h>
 
 
-// A class to handle substrates prms in gerber job file and dialog
+// A class to handle substrates prms in gerber job file and dialog.
 struct DIELECTRIC_SUBSTRATE
 {
     wxString m_Name;            // the name (in job file) of material
@@ -44,10 +44,10 @@ struct DIELECTRIC_SUBSTRATE
 };
 
 
-// A struct to handle a list of substrates prms in gerber job file and dialogs
+// Handle a list of substrates prms in gerber job file and dialogs
 class DIELECTRIC_SUBSTRATE_LIST
 {
-    ///> The list of available substrates. It contians at least predefined substrates
+    ///< The list of available substrates. It contains at least predefined substrates
     std::vector<DIELECTRIC_SUBSTRATE> m_substrateList;
 
 public:
@@ -58,10 +58,9 @@ public:
         DL_MATERIAL_SILKSCREEN
     };
 
-    /** Ctor
+    /**
-     * @param aForDielectric =
+     * @param aForDielectric set to #DL_MATERIAL_DIELECTRIC to build a dielectric material list
-     * DL_MATERIAL_DIELECTRIC to build a dielectric material list
+     *                       or #DL_MATERIAL_SOLDERMASK to build a solder mask material list.
-     * DL_MATERIAL_SOLDERMASK to build a solder mask material list
      */
     DIELECTRIC_SUBSTRATE_LIST( DL_MATERIAL_LIST_TYPE aListType);
 
@@ -71,38 +70,45 @@ public:
     int GetCount() { return (int)m_substrateList.size(); }
 
     /**
-     * @return the substrate in list of index aIdx
+     * @return the substrate in list of index \a aIdx if incorrect return nullptr.
-     *  if incorrect return nullptr
+     *
      * @param aIdx is the index in substrate list.
      */
     DIELECTRIC_SUBSTRATE* GetSubstrate( int aIdx );
 
     /**
-     * @return the substrate in list of name aName
+     * The comparison is case insensitive.
-     *  if not found return nullptr
+     *
      * @param aName is the name of the substrate in substrate list.
-     * the comparison is case insensitve
+     * @return the substrate in list of name \a aName if not found return nullptr.
      */
     DIELECTRIC_SUBSTRATE* GetSubstrate( const wxString& aName );
 
-    /** Find a item in list similar to aItem
+    /**
-     * @param aItem is the item to match
+     * Find a item in list similar to \a aItem.
-     * @return the index of similar item in list or -1 if not found
+     *
-     * the comparison is for the name case insensitive, and EpsilonR and LossTg must match
+     * The comparison is for the name case insensitive, and EpsilonR and LossTg must match.
+     *
+     * @param aItem is the item to match.
+     * @return the index of similar item in list or -1 if not found.
      */
     int FindSubstrate( DIELECTRIC_SUBSTRATE* aItem );
 
-    /** Find a item in list having the sapme parameters
+    /**
-     * @param aName is the name to match (case insensitive)
+     * Find a item in list having the same parameters.
-     * @param aEpsilonR is the Repaltive Permeatbility to match
+     *
-     * @param aLossTg is the loss tangent to match
+     * @param aName is the name to match (case insensitive).
-     * @return the index of similar item in list or -1 if not found
+     * @param aEpsilonR is the relative permeability to match.
+     * @param aLossTg is the loss tangent to match.
+     * @return the index of similar item in list or -1 if not found.
      */
     int FindSubstrate( const wxString& aName, double aEpsilonR, double aLossTg );
 
-    /** Append a item in list similar to aItem
+    /**
-     * @param aItem is the item to append
+     * Append a item in list similar to \a aItem.
-     * @return the index of the new item in list
+     *
+     * @param aItem is the item to append.
+     * @return the index of the new item in list.
      */
     int AppendSubstrate( DIELECTRIC_SUBSTRATE& aItem )
     {

pcbnew/connectivity/connectivity_algo.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2013-2017 CERN
- * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
@@ -68,9 +69,10 @@ public:
     {}
 
     /**
-     * This sort operator provides a sort-by-weight for the ratsnest operation
+     * This sort operator provides a sort-by-weight for the ratsnest operation.
-     * @param aOther Other edge to compare
+     *
-     * @return true if our weight is smaller than the other weight
+     * @param aOther the other edge to compare.
+     * @return true if our weight is smaller than the other weight.
      */
     bool operator<( CN_EDGE aOther ) const
     {
@@ -155,7 +157,6 @@ public:
     };
 
 private:
-
     CN_LIST m_itemList;
 
     std::unordered_map<const BOARD_ITEM*, ITEM_MAP_ENTRY> m_itemMap;
@@ -180,7 +181,6 @@ private:
     void markItemNetAsDirty( const BOARD_ITEM* aItem );
 
 public:
-
     CN_CONNECTIVITY_ALGO() {}
     ~CN_CONNECTIVITY_ALGO() { Clear(); }
 
@@ -281,13 +281,9 @@ public:
     void SetProgressReporter( PROGRESS_REPORTER* aReporter );
 };
 
-/**
+class CN_VISITOR
- * Struct CN_VISTOR
+{
- **/
-class CN_VISITOR {
-
 public:
-
     CN_VISITOR( CN_ITEM* aItem ) :
         m_item( aItem )
     {}
@@ -295,12 +291,11 @@ public:
     bool operator()( CN_ITEM* aCandidate );
 
 protected:
-
     void checkZoneItemConnection( CN_ZONE_LAYER* aZoneLayer, CN_ITEM* aItem );
 
     void checkZoneZoneConnection( CN_ZONE_LAYER* aZoneLayerA, CN_ZONE_LAYER* aZoneLayerB );
 
-    ///> the item we are looking for connections to
+    ///< The item we are looking for connections to.
     CN_ITEM* m_item;
 };
 

pcbnew/connectivity/connectivity_items.cpp

@@ -1,8 +1,9 @@
+
 /*
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2016-2018 CERN
- * Copyright (C) 2019  KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *

pcbnew/connectivity/connectivity_items.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2013-2017 CERN
- * Copyright (C) 2018-2020  KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
@@ -91,25 +91,25 @@ public:
         return ( m_pos - aSecond.Pos() ).EuclideanNorm();
     }
 
-    /// Returns tag, common identifier for connected nodes
+    ///< Return tag, common identifier for connected nodes.
     inline int GetTag() const
     {
         return m_tag;
     }
 
-    /// Sets tag, common identifier for connected nodes
+    ///< Set tag, common identifier for connected nodes.
     inline void SetTag( int aTag )
     {
         m_tag = aTag;
     }
 
-    /// Decides whether this node can be a ratsnest line target
+    ///< Decide whether this node can be a ratsnest line target.
     inline void SetNoLine( bool aEnable )
     {
         m_noline = aEnable;
     }
 
-    /// Returns true if this node can be a target for ratsnest lines
+    ///< Return true if this node can be a target for ratsnest lines.
     inline const bool& GetNoLine() const
     {
         return m_noline;
@@ -126,18 +126,16 @@ public:
     }
 
     /**
-     * has meaning only for tracks and vias.
+     * The anchor point is dangling if the parent is a track and this anchor point is not
-     * @return true if this anchor is dangling
+     * connected to another item ( track, vas pad or zone) or if the parent is a via and
-     * The anchor point is dangling if the parent is a track
+     * this anchor point is connected to only one track and not to another item.
-     * and this anchor point is not connected to another item
+     *
-     * ( track, vas pad or zone) or if the parent is a via and this anchor point
+     * @return true if this anchor is dangling.
-     * is connected to only one track and not to another item
      */
     bool IsDangling() const;
 
     /**
-     * has meaning only for tracks and vias.
+     * @return the count of tracks and vias connected to this anchor.
-     * @return the count of items connected to this anchor
      */
     int ConnectedItemsCount() const;
 
@@ -145,19 +143,19 @@ public:
     static const int TAG_UNCONNECTED = -1;
 
 private:
-    /// Position of the anchor
+    ///< Position of the anchor.
     VECTOR2I m_pos;
 
-    /// Item owning the anchor
+    ///< Item owning the anchor.
     CN_ITEM* m_item = nullptr;
 
-    /// Tag for quick connection resolution
+    ///< Tag for quick connection resolution.
     int m_tag = -1;
 
-    /// Whether it the node can be a target for ratsnest lines
+    ///< Whether it the node can be a target for ratsnest lines.
     bool m_noline = false;
 
-    /// Cluster to which the anchor belongs
+    ///< Cluster to which the anchor belongs.
     std::shared_ptr<CN_CLUSTER> m_cluster;
 };
 
@@ -172,26 +170,6 @@ class CN_ITEM
 public:
     using CONNECTED_ITEMS = std::vector<CN_ITEM*>;
 
-private:
-    BOARD_CONNECTED_ITEM* m_parent;
-
-    CONNECTED_ITEMS m_connected;      ///> list of items physically connected (touching)
-    CN_ANCHORS      m_anchors;
-
-    bool            m_canChangeNet;  ///> can the net propagator modify the netcode?
-
-    bool            m_visited;       ///> visited flag for the BFS scan
-    bool            m_valid;         ///> used to identify garbage items (we use lazy removal)
-
-    std::mutex      m_listLock;      ///> mutex protecting this item's connected_items set to
-                                     ///> allow parallel connection threads
-protected:
-    bool            m_dirty;         ///> used to identify recently added item not yet
-                                     ///> scanned into the connectivity search
-    LAYER_RANGE     m_layers;        ///> layer range over which the item exists
-    BOX2I           m_bbox;          ///> bounding box for the item
-
-public:
     void Dump();
 
     CN_ITEM( BOARD_CONNECTED_ITEM* aParent, bool aCanChangeNet, int aAnchorCount = 2 )
@@ -222,9 +200,7 @@ public:
     bool Dirty() const { return m_dirty;  }
 
     /**
-     * Function SetLayers()
+     * Set the layers spanned by the item to aLayers.
-     *
-     * Sets the layers spanned by the item to aLayers.
      */
     void SetLayers( const LAYER_RANGE& aLayers )
     {
@@ -232,9 +208,7 @@ public:
     }
 
     /**
-     * Function SetLayer()
+     * Set the layers spanned by the item to a single layer aLayer.
-     *
-     * Sets the layers spanned by the item to a single layer aLayer.
      */
     void SetLayer( int aLayer )
     {
@@ -242,9 +216,7 @@ public:
     }
 
     /**
-     * Function Layers()
+     * Return the contiguous set of layers spanned by the item.
-     *
-     * Returns the contiguous set of layers spanned by the item.
      */
     const LAYER_RANGE& Layers() const
     {
@@ -252,9 +224,7 @@ public:
     }
 
     /**
-     * Function Layer()
+     * Return the item's layer, for single-layered items only.
-     *
-     * Returns the item's layer, for single-layered items only.
      */
     virtual int Layer() const
     {
@@ -305,6 +275,25 @@ public:
     {
         return ( !m_parent || !m_valid ) ? -1 : m_parent->GetNetCode();
     }
+                                     ///< allow parallel connection threads
+protected:
+    bool            m_dirty;         ///< used to identify recently added item not yet
+                                     ///< scanned into the connectivity search
+    LAYER_RANGE     m_layers;        ///< layer range over which the item exists
+    BOX2I           m_bbox;          ///< bounding box for the item
+
+private:
+    BOARD_CONNECTED_ITEM* m_parent;
+
+    CONNECTED_ITEMS m_connected;     ///< list of items physically connected (touching)
+    CN_ANCHORS      m_anchors;
+
+    bool            m_canChangeNet;  ///< can the net propagator modify the netcode?
+
+    bool            m_visited;       ///< visited flag for the BFS scan
+    bool            m_valid;         ///< used to identify garbage items (we use lazy removal)
+
+    std::mutex      m_listLock;      ///< mutex protecting this item's connected_items set to
 };
 
 typedef std::shared_ptr<CN_ITEM> CN_ITEM_PTR;
@@ -366,12 +355,6 @@ private:
 
 class CN_LIST
 {
-private:
-    bool                  m_dirty;
-    bool                  m_hasInvalid;
-
-    CN_RTREE<CN_ITEM*>    m_index;
-
 protected:
     std::vector<CN_ITEM*> m_items;
 
@@ -457,14 +440,20 @@ public:
     CN_ITEM* Add( VIA* via );
 
     const std::vector<CN_ITEM*> Add( ZONE* zone, PCB_LAYER_ID aLayer );
+
+private:
+    bool                  m_dirty;
+    bool                  m_hasInvalid;
+
+    CN_RTREE<CN_ITEM*>    m_index;
 };
 
 class CN_CLUSTER
 {
 private:
-    bool                  m_conflicting = false;
+    bool                  m_conflicting;
-    int                   m_originNet = 0;
+    int                   m_originNet;
-    CN_ITEM*              m_originPad = nullptr;
+    CN_ITEM*              m_originPad;
     std::vector<CN_ITEM*> m_items;
 
 public:

pcbnew/dialogs/dialog_board_statistics.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2019 Alexander Shuklin, jasuramme@gmail.com
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -39,15 +39,13 @@
 #include <wx/datetime.h>
 
 /**
- * DIALOG_BOARD_STATISTIC
- *
  * Dialog to show common board info.
  */
 class DIALOG_BOARD_STATISTICS : public DIALOG_BOARD_STATISTICS_BASE
 {
 public:
     /**
-     * Struct to hold type information, which will be shown in dialog.
+     * Type information, which will be shown in dialog.
      */
     template <typename T>
     struct typeContainer_t
@@ -58,6 +56,7 @@ public:
                   qty( 0 )
         {
         }
+
         T          attribute;
         wxString   title;
         int        qty;
@@ -67,9 +66,8 @@ public:
     using viasType_t = typeContainer_t<VIATYPE>;
 
     /**
-     * Struct holds information about component type (such as SMD, THT,
+     * Footprint attributes (such as SMD, THT, Virtual and so on), which will be shown in the
-     * Virtual and so on), which will be shown in the dialog. Holds both
+     * dialog. Holds both front and bottom components quantities.
-     * front and bottom components quantities
      */
     struct componentsType_t
     {
@@ -80,6 +78,7 @@ public:
                   backSideQty( 0 )
         {
         }
+
         FOOTPRINT_ATTR_T attribute;
         wxString         title;
         int              frontSideQty;
@@ -99,6 +98,7 @@ public:
             COL_START_LAYER,
             COL_STOP_LAYER
         };
+
         drillType_t( int aXSize, int aYSize, PAD_DRILL_SHAPE_T aShape, bool aIsPlated, bool aIsPad,
                 PCB_LAYER_ID aStartLayer, PCB_LAYER_ID aStopLayer, int aQty = 0 )
                 : xSize( aXSize ),
@@ -111,12 +111,14 @@ public:
                   qty( aQty )
         {
         }
+
         bool operator==( const drillType_t& other )
         {
             return xSize == other.xSize && ySize == other.ySize && shape == other.shape
                    && isPlated == other.isPlated && isPad == other.isPad
                    && startLayer == other.startLayer && stopLayer == other.stopLayer;
         }
+
         struct COMPARE
         {
             COMPARE( COL_ID aColId, bool aAscending ) : colId( aColId ), ascending( aAscending )
@@ -146,13 +148,16 @@ public:
 
                 return false;
             }
+
             bool compareDrillParameters( int aLeft, int aRight )
             {
                 return ascending ? aLeft < aRight : aLeft > aRight;
             }
+
             COL_ID colId;
             bool   ascending;
         };
+
         int               xSize;
         int               ySize;
         PAD_DRILL_SHAPE_T shape;
@@ -171,44 +176,24 @@ public:
     DIALOG_BOARD_STATISTICS( PCB_EDIT_FRAME* aParentFrame );
     ~DIALOG_BOARD_STATISTICS();
 
-    ///> Get data from the PCB board and print it to dialog
+    ///< Get data from the PCB board and print it to dialog
     bool TransferDataToWindow() override;
 
 private:
-    PCB_EDIT_FRAME* m_parentFrame;
 
-    int             m_boardWidth;
+    ///< Function to fill up all items types to be shown in the dialog.
-    int             m_boardHeight;
-    double          m_boardArea;
-
-    ///> Shows if board outline properly defined
-    bool m_hasOutline;
-
-    ///> Holds all components types to be shown in the dialog
-    componentsTypeList_t m_componentsTypes;
-
-    ///> Holds all pads types to be shown in the dialog
-    padsTypeList_t  m_padsTypes;
-
-    ///> Holds all vias types to be shown in the dialog
-    viasTypeList_t m_viasTypes;
-
-    ///> Holds all drill hole types to be shown in the dialog
-    drillTypeList_t m_drillTypes;
-
-    ///> Function to fill up all items types to be shown in the dialog.
     void refreshItemsTypes();
 
-    ///> Gets data from board
+    ///< Get data from board.
     void getDataFromPCB();
 
-    ///> Applies data to dialog widgets
+    ///< Apply data to dialog widgets.
     void updateWidets();
 
-    ///> Updates drills grid
+    ///< Update drills grid.
     void updateDrillGrid();
 
-    ///> Prints grid to string in tabular format
+    ///< Print grid to string in tabular format.
     void printGridToStringAsTable( wxGrid* aGrid, wxString& aStr, bool aUseRowLabels,
             bool aUseColLabels, bool aUseFirstColAsLabel );
 
@@ -216,12 +201,33 @@ private:
 
     void checkboxClicked( wxCommandEvent& aEvent ) override;
 
-    ///> Save board statistics to a file
+    ///< Save board statistics to a file
     void saveReportClicked( wxCommandEvent& aEvent ) override;
 
     void drillGridSize( wxSizeEvent& aEvent ) override;
 
     void drillGridSort( wxGridEvent& aEvent );
+
+    PCB_EDIT_FRAME* m_parentFrame;
+
+    int             m_boardWidth;
+    int             m_boardHeight;
+    double          m_boardArea;
+
+    ///< Show if board outline properly defined.
+    bool m_hasOutline;
+
+    ///< Hold all components types to be shown in the dialog.
+    componentsTypeList_t m_componentsTypes;
+
+    ///< Hold all pads types to be shown in the dialog.
+    padsTypeList_t  m_padsTypes;
+
+    ///< Hold all vias types to be shown in the dialog.
+    viasTypeList_t m_viasTypes;
+
+    ///< Hold all drill hole types to be shown in the dialog.
+    drillTypeList_t m_drillTypes;
 };
 
 #endif // __DIALOG_BOARD_STATISTICS_H

pcbnew/dialogs/dialog_enum_pads.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -26,23 +28,20 @@
 #define __dialog_enum_pads__
 
 /**
-@file
+ * @file Subclass of DIALOG_ENUM_PADS_BASE which is generated by wxFormBuilder.
-Subclass of DIALOG_ENUM_PADS_BASE, which is generated by wxFormBuilder.
  */
 
 #include "dialog_enum_pads_base.h"
 
-/** Implementing DIALOG_ENUM_PADS_BASE */
 class DIALOG_ENUM_PADS : public DIALOG_ENUM_PADS_BASE
 {
 public:
-    /** Constructor */
     DIALOG_ENUM_PADS( wxWindow* parent );
 
-    ///> Returns the starting number that is going to be used for the first enumerated pad.
+    ///< Return the starting number that is going to be used for the first enumerated pad.
     int GetStartNumber() const;
 
-    ///> Returns common prefix for all enumerated pads.
+    ///< Return common prefix for all enumerated pads.
     wxString GetPrefix() const;
 };
 

pcbnew/dialogs/dialog_gencad_export_options.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2017 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -30,7 +32,7 @@
 class PCB_EDIT_FRAME;
 class wxFilePickerCtrl;
 
-///> Settings for GenCAD exporter
+///< Settings for GenCAD exporter
 enum GENCAD_EXPORT_OPT
 {
     FLIP_BOTTOM_PADS,       // flip bottom components padstacks geometry
@@ -47,19 +49,19 @@ public:
     DIALOG_GENCAD_EXPORT_OPTIONS( PCB_EDIT_FRAME* aParent, const wxString& aPath );
     ~DIALOG_GENCAD_EXPORT_OPTIONS();
 
-    ///> Checks whether an option has been selected
+    ///< Check whether an option has been selected.
     bool GetOption( GENCAD_EXPORT_OPT aOption ) const;
 
-    ///> Returns all export settings
+    ///< Return all export settings.
     std::map<GENCAD_EXPORT_OPT, bool> GetAllOptions() const;
 
-    ///> Returns the selected file path
+    ///< Return the selected file path.
     wxString GetFileName() const;
 
 protected:
     bool TransferDataFromWindow() override;
 
-    ///> Creates checkboxes for GenCAD export options
+    ///< Create checkboxes for GenCAD export options.
     void createOptCheckboxes();
 
     std::map<GENCAD_EXPORT_OPT, wxCheckBox*> m_options;

pcbnew/dialogs/dialog_print_pcbnew.cpp

@@ -2,9 +2,10 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2010-2016 Jean-Pierre Charras, jean-pierre.charras at wanadoo.fr
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  * Copyright (C) 2018 CERN
- * Author: Maciej Suminski <maciej.suminski@cern.ch>
+ *
+ * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -37,6 +38,7 @@
 #include <dialogs/dialog_print_generic.h>
 #include <pcbnew_printout.h>
 
+
 class DIALOG_PRINT_PCBNEW : public DIALOG_PRINT_GENERIC
 {
 public:
@@ -61,16 +63,16 @@ private:
     void onUseThemeChecked( wxCommandEvent& event );
     void onColorModeChanged( wxCommandEvent& event );
 
-    ///> (Un)checks all items in a checklist box
+    ///< (Un)check all items in a checklist box.
     void setListBoxValue( wxCheckListBox* aList, bool aValue );
 
-    ///> Check whether a layer is enabled in a listbox
+    ///< Check whether a layer is enabled in a listbox.
     bool isLayerEnabled( unsigned int aLayer ) const;
 
-    ///> Enable/disable layer in a listbox
+    ///< Enable/disable layer in a listbox.
     void enableLayer( unsigned int aLayer, bool aValue );
 
-    ///> Update layerset basing on the selected layers
+    ///< Update layerset basing on the selected layers.
     int setLayerSetFromList();
 
     void saveSettings() override;

pcbnew/dialogs/panel_setup_layers.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2018-2020 KiCad Developers, see change_log.txt for contributors.
+ * Copyright (C) 2018-2021 KiCad Developers, see change_log.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -35,7 +35,7 @@ class BOARD_DESIGN_SETTINGS;
 
 
 /**
- * Holds the 3 UI control pointers for a single board layer.
+ * The 3 UI control pointers for a single board layer.
  */
 struct PANEL_SETUP_LAYERS_CTLs
 {
@@ -65,17 +65,17 @@ public:
      * This function warns users if they are going to delete inner copper layers because
      * they're importing settings from a board with less copper layers than the board
      * already loaded.
-     * @param aWorkingBoard = Currently loaded PCB
-     * @param aImportedBoard = PCB imported to get settings from
      *
-     * @return bool - Approval to delete inner copper if needed
+     * @param aWorkingBoard is the currently loaded PCB
+     * @param aImportedBoard is the PCB imported to get settings from.
+     * @return Approval to delete inner copper if needed.
      */
     bool CheckCopperLayerCount( BOARD* aWorkingBoard, BOARD* aImportedBoard );
 
-    ///> @return the selected layer mask within the UI checkboxes
+    ///< @return the selected layer mask within the UI checkboxes
     LSET GetUILayerMask();
 
-    ///> @return the layer name within the UI wxTextCtrl
+    ///< @return the layer name within the UI wxTextCtrl
     wxString GetLayerName( LAYER_NUM layer );
 
 private:

pcbnew/files.cpp

@@ -3,7 +3,7 @@
  *
  * Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
  * Copyright (C) 2011 Wayne Stambaugh <stambaughw@gmail.com>
- * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -64,16 +64,13 @@
 
 
 /**
- * Function AskLoadBoardFileName
+ * Show a wxFileDialog asking for a #BOARD filename to open.
- * puts up a wxFileDialog asking for a BOARD filename to open.
  *
  * @param aParent is a wxFrame passed to wxFileDialog.
  * @param aCtl is where to put the OpenProjectFiles() control bits.
- *
  * @param aFileName on entry is a probable choice, on return is the chosen filename.
- * @param aKicadFilesOnly true to list kiacad pcb files plugins only, false to list import plugins.
+ * @param aKicadFilesOnly true to list KiCad pcb files plugins only, false to list import plugins.
- *
+ * @return  true if chosen, else false if user aborted.
- * @return bool - true if chosen, else false if user aborted.
  */
 bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bool aKicadFilesOnly )
 {
@@ -89,15 +86,32 @@ bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bo
         IO_MGR::PCB_FILE_T  pluginType;
     } loaders[] =
     {
-        { PcbFileWildcard(),                    IO_MGR::KICAD_SEXP },            // Current Kicad board files
+        // Current Kicad board files.
-        { LegacyPcbFileWildcard(),              IO_MGR::LEGACY },                // Old Kicad board files
+        { PcbFileWildcard(),                    IO_MGR::KICAD_SEXP },
-        { AltiumCircuitMakerPcbFileWildcard(),  IO_MGR::ALTIUM_CIRCUIT_MAKER },  // Import Altium Circuit Maker board files
+
-        { AltiumCircuitStudioPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_STUDIO }, // Import Altium Circuit Studio board files
+        // Old Kicad board files.
-        { AltiumDesignerPcbFileWildcard(),      IO_MGR::ALTIUM_DESIGNER },       // Import Altium Designer board files
+        { LegacyPcbFileWildcard(),              IO_MGR::LEGACY },
-        { CadstarPcbArchiveFileWildcard(),      IO_MGR::CADSTAR_PCB_ARCHIVE },   // Import Cadstar PCB Archive board files
+
-        { EaglePcbFileWildcard(),               IO_MGR::EAGLE },                 // Import Eagle board files
+        // Import Altium Circuit Maker board files.
-        { PCadPcbFileWildcard(),                IO_MGR::PCAD },                  // Import PCAD board files
+        { AltiumCircuitMakerPcbFileWildcard(),  IO_MGR::ALTIUM_CIRCUIT_MAKER },
-        { FabmasterPcbFileWildcard(),           IO_MGR::FABMASTER },             // Import Fabmaster board files
+
+        // Import Altium Circuit Studio board files.
+        { AltiumCircuitStudioPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_STUDIO },
+
+        // Import Altium Designer board files.
+        { AltiumDesignerPcbFileWildcard(),      IO_MGR::ALTIUM_DESIGNER },
+
+        // Import Cadstar PCB Archive board files.
+        { CadstarPcbArchiveFileWildcard(),      IO_MGR::CADSTAR_PCB_ARCHIVE },
+
+        // Import Eagle board files.
+        { EaglePcbFileWildcard(),               IO_MGR::EAGLE },
+
+        // Import PCAD board files.
+        { PCadPcbFileWildcard(),                IO_MGR::PCAD },
+
+        // Import Fabmaster board files.
+        { FabmasterPcbFileWildcard(),           IO_MGR::FABMASTER },
     };
     // clang-format on
 
@@ -176,7 +190,7 @@ bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bo
 }
 
 
-///> Helper widget to select whether a new project should be created for a file when saving
+///< Helper widget to select whether a new project should be created for a file when saving
 class CREATE_PROJECT_CHECKBOX : public wxPanel
 {
 public:
@@ -211,14 +225,13 @@ protected:
 
 
 /**
- * Puts up a wxFileDialog asking for a BOARD filename to save.
+ * Put up a wxFileDialog asking for a BOARD filename to save.
  *
  * @param aParent is a wxFrame passed to wxFileDialog.
- * @param aFileName on entry is a probable choice, on return is the
+ * @param aFileName on entry is a probable choice, on return is the chosen full filename
- *  chosen full filename (includes path).
+ *                  (includes path).
- * @param aCreateProject will be filled with the state of the Create Project? checkbox if relevant
+ * @param aCreateProject will be filled with the state of the Create Project? checkbox if relevant.
- *
+ * @return true if chosen, else false if user aborted.
- * @return bool - true if chosen, else false if user aborted.
  */
 bool AskSaveBoardFileName( PCB_EDIT_FRAME* aParent, wxString* aFileName, bool* aCreateProject )
 {
@@ -227,13 +240,8 @@ bool AskSaveBoardFileName( PCB_EDIT_FRAME* aParent, wxString* aFileName, bool* a
 
     fn.SetExt( KiCadPcbFileExtension );
 
-    wxFileDialog dlg( aParent,
+    wxFileDialog dlg( aParent, _( "Save Board File As" ), fn.GetPath(), fn.GetFullName(), wildcard,
-            _( "Save Board File As" ),
+                      wxFD_SAVE | wxFD_OVERWRITE_PROMPT );
-            fn.GetPath(),
-            fn.GetFullName(),
-            wildcard,
-            wxFD_SAVE | wxFD_OVERWRITE_PROMPT
-            );
 
     // Add a "Create a project" checkbox in standalone mode and one isn't loaded
     if( Kiface().IsSingle() && aParent->Prj().IsNullProject() )
@@ -520,7 +528,8 @@ int PCB_EDIT_FRAME::inferLegacyEdgeClearance( BOARD* aBoard )
         wxMessageBox( _( "If the zones on this board are refilled the Copper Edge Clearance "
                          "setting will be used (see Board Setup > Design Rules > Constraints).\n"
                          "This may result in different fills from previous Kicad versions which "
-                         "used the line thicknesses of the board boundary on the Edge Cuts layer." ),
+                         "used the line thicknesses of the board boundary on the Edge Cuts "
+                          "layer." ),
                       _( "Edge Clearance Warning" ), wxOK | wxICON_WARNING, this );
     }
 
@@ -578,14 +587,15 @@ bool PCB_EDIT_FRAME::OpenProjectFiles( const std::vector<wxString>& aFileSet, in
     if( is_new && !( aCtl & KICTL_CREATE ) )
     {
         // notify user that fullFileName does not exist, ask if user wants to create it.
-        wxString ask = wxString::Format( _( "PCB \"%s\" does not exist.  Do you wish to create it?" ),
+        wxString ask = wxString::Format( _( "PCB \"%s\" does not exist.  Do you wish to "
+                                             "create it?" ),
                                          fullFileName );
         if( !IsOK( this, ask ) )
             return false;
     }
 
     // Loading a complex project and build data can be time
-    // consumming, so display a busy cursor
+    // consuming, so display a busy cursor
     wxBusyCursor dummy;
 
     // No save prompt (we already prompted above), and only reset to a new blank board if new
@@ -811,7 +821,6 @@ bool PCB_EDIT_FRAME::SavePcbFile( const wxString& aFileName, bool addToHistory,
                                   bool aChangeProject )
 {
     // please, keep it simple.  prompting goes elsewhere.
-
     wxFileName pcbFileName = aFileName;
 
     if( pcbFileName.GetExt() == LegacyPcbFileExtension )
@@ -981,10 +990,8 @@ bool PCB_EDIT_FRAME::SavePcbCopy( const wxString& aFileName, bool aCreateProject
     }
     catch( const IO_ERROR& ioe )
     {
-        wxString msg = wxString::Format( _(
+        wxString msg = wxString::Format( _( "Error saving board file \"%s\".\n%s" ),
-                "Error saving board file \"%s\".\n%s" ),
+                                         pcbFileName.GetFullPath(), ioe.What() );
-                pcbFileName.GetFullPath(), ioe.What()
-                );
         DisplayError( this, msg );
 
         return false;
@@ -1051,7 +1058,7 @@ bool PCB_EDIT_FRAME::doAutoSave()
         return false;
 
     // If the board file path is not writable, try writing to a platform specific temp file
-    // path.  If that path isn't writabe, give up.
+    // path.  If that path isn't writable, give up.
     if( !autoSaveFileName.IsDirWritable() )
     {
         autoSaveFileName.SetPath( wxFileName::GetTempDir() );
@@ -1144,7 +1151,6 @@ bool PCB_EDIT_FRAME::importFile( const wxString& aFileName, int aFileType )
                 }
             }
 
-
             // Update footprint LIB_IDs to point to the just imported library
             for( FOOTPRINT* footprint : GetBoard()->Footprints() )
             {

pcbnew/footprint.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -59,8 +59,7 @@ enum INCLUDE_NPTH_T
 };
 
 /**
- * Enum FOOTPRINT_ATTR_T
+ * The set of attributes allowed within a FOOTPRINT, using FOOTPRINT::SetAttributes()
- * is the set of attributes allowed within a FOOTPRINT, using FOOTPRINT::SetAttributes()
  * and FOOTPRINT::GetAttributes().  These are to be ORed together when calling
  * FOOTPRINT::SetAttributes()
  */
@@ -125,53 +124,56 @@ public:
         return aItem && aItem->Type() == PCB_FOOTPRINT_T;
     }
 
-    ///> @copydoc BOARD_ITEM_CONTAINER::Add()
+    ///< @copydoc BOARD_ITEM_CONTAINER::Add()
     void Add( BOARD_ITEM* aItem, ADD_MODE aMode = ADD_MODE::INSERT ) override;
 
-    ///> @copydoc BOARD_ITEM_CONTAINER::Remove()
+    ///< @copydoc BOARD_ITEM_CONTAINER::Remove()
     void Remove( BOARD_ITEM* aItem, REMOVE_MODE aMode = REMOVE_MODE::NORMAL ) override;
 
     /**
-     * Function ClearAllNets
      * Clear (i.e. force the ORPHANED dummy net info) the net info which
      * depends on a given board for all pads of the footprint.
+     *
      * This is needed when a footprint is copied between the fp editor and
      * the board editor for instance, because net info become fully broken
      */
     void ClearAllNets();
 
     /**
-     * Function CalculateBoundingBox
+     * Calculate the bounding box in board coordinates.
-     * calculates the bounding box in board coordinates.
      */
     void CalculateBoundingBox();
 
     /**
-     * Function GetFootprintRect()
      * Build and returns the boundary box of the footprint excluding any text.
-     * @return EDA_RECT - The rectangle containing the footprint.
+     *
+     * @return The rectangle containing the footprint.
      */
     EDA_RECT GetFootprintRect() const;
 
     /**
-     * Returns the last calculated bounding box of the footprint (does not recalculate it).
+     * Return the last calculated bounding box of the footprint (does not recalculate it).
-     * (call CalculateBoundingBox() to recalculate it)
+     * (call CalculateBoundingBox() to recalculate it).
-     * @return EDA_RECT - The rectangle containing the footprint
+     *
+     * @return The rectangle containing the footprint.
      */
     EDA_RECT GetBoundingBoxBase() const { return m_boundingBox; }
 
     /**
-     * Returns the bounding box containing pads when the footprint
+     * Return the bounding box containing pads when the footprint is on the front side,
-     * is on the front side, orientation 0, position 0,0.
+     * orientation 0, position 0,0.
-     * mainly used in Gerber place file to draw a fp outline when the coutyard
+     *
-     * is missing or broken
+     * Mainly used in Gerber place file to draw a footprint outline when the courtyard
-     * @return EDA_RECT - The rectangle containing the pads for the normalized footprint.
+     * is missing or broken.
+     *
+     * @return The rectangle containing the pads for the normalized footprint.
      */
     EDA_RECT GetFpPadsLocalBbox() const;
 
     /**
-     * Returns a bounding polygon for the shapes and pads in the footprint
+     * Return a bounding polygon for the shapes and pads in the footprint.
-     * This operation is slower but more accurate than calculating a bounding box
+     *
+     * This operation is slower but more accurate than calculating a bounding box.
      */
     SHAPE_POLY_SET GetBoundingHull() const;
 
@@ -263,8 +265,8 @@ public:
     void Flip( const wxPoint& aCentre, bool aFlipLeftRight ) override;
 
     /**
-     * Function MoveAnchorPosition
+     * Move the reference point of the footprint.
-     * Move the reference point of the footprint
+     *
      * It looks like a move footprint:
      * the footprints elements (pads, outlines, edges .. ) are moved
      * However:
@@ -276,7 +278,6 @@ public:
     void MoveAnchorPosition( const wxPoint& aMoveVector );
 
     /**
-     * function IsFlipped
      * @return true if the footprint is flipped, i.e. on the back side of the board
      */
     bool IsFlipped() const { return GetLayer() == B_Cu; }
@@ -301,9 +302,9 @@ public:
     }
 
     /**
-     * Function SetLocked
+     * Set the #MODULE_is_LOCKED bit in the m_ModuleStatus.
-     * sets the MODULE_is_LOCKED bit in the m_ModuleStatus
+     *
-     * @param isLocked When true means turn on locked status, else unlock
+     * @param isLocked true means turn on locked status, else unlock
      */
     void SetLocked( bool isLocked ) override
     {
@@ -347,25 +348,25 @@ public:
     void SetLastEditTime() { m_lastEditTime = time( NULL ); }
     timestamp_t GetLastEditTime() const { return m_lastEditTime; }
 
-    /* drawing functions */
-
     /**
-     * function TransformPadsShapesWithClearanceToPolygon
+     * Generate pads shapes on layer \a aLayer as polygons and adds these polygons to
-     * generate pads shapes on layer aLayer as polygons and adds these polygons to aCornerBuffer
+     * \a aCornerBuffer.
+     *
      * Useful to generate a polygonal representation of a footprint in 3D view and plot functions,
-     * when a full polygonal approach is needed
+     * when a full polygonal approach is needed.
-     * @param aLayer = the layer to consider, or UNDEFINED_LAYER to consider all
+     *
-     * @param aCornerBuffer = the buffer to store polygons
+     * @param aLayer is the layer to consider, or #UNDEFINED_LAYER to consider all layers.
-     * @param aClearance = an additionnal size to add to pad shapes
+     * @param aCornerBuffer i the buffer to store polygons.
-     * @param aMaxError = Maximum deviation from true for arcs
+     * @param aClearance is an additional size to add to pad shapes.
-     * @param aSkipNPTHPadsWihNoCopper = if true, do not add a NPTH pad shape, if the shape has
+     * @param aMaxError is the maximum deviation from true for arcs.
+     * @param aSkipNPTHPadsWihNoCopper if true, do not add a NPTH pad shape, if the shape has
      *          same size and position as the hole. Usually, these pads are not drawn on copper
      *          layers, because there is actually no copper
      *          Due to diff between layers and holes, these pads must be skipped to be sure
      *          there is no copper left on the board (for instance when creating Gerber Files or
      *          3D shapes).  Defaults to false.
-     * @param aSkipPlatedPads = used on 3D-Viewer to extract plated and nontplated pads.
+     * @param aSkipPlatedPads is used on 3D-Viewer to extract plated and non-plated pads.
-     * @param aSkipNonPlatedPads = used on 3D-Viewer to extract plated and plated pads.
+     * @param aSkipNonPlatedPads is used on 3D-Viewer to extract plated and plated pads.
      */
     void TransformPadsWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer,
                                               PCB_LAYER_ID aLayer, int aClearance,
@@ -375,17 +376,18 @@ public:
                                               bool aSkipNonPlatedPads = false ) const;
 
     /**
-     * function TransformFPShapesWithClearanceToPolygon
+     * Generate shapes of graphic items (outlines) on layer \a aLayer as polygons and adds these
-     * generate shapes of graphic items (outlines) on layer aLayer as polygons and adds these
+     * polygons to \a aCornerBuffer.
-     * polygons to aCornerBuffer
+     *
      * Useful to generate a polygonal representation of a footprint in 3D view and plot functions,
-     * when a full polygonal approach is needed
+     * when a full polygonal approach is needed.
-     * @param aLayer = the layer to consider, or UNDEFINED_LAYER to consider all
+     *
-     * @param aCornerBuffer = the buffer to store polygons
+     * @param aLayer is the layer to consider, or #UNDEFINED_LAYER to consider all.
-     * @param aClearance = a value to inflate shapes
+     * @param aCornerBuffer is the buffer to store polygons.
-     * @param aError = Maximum error between true arc and polygon approx
+     * @param aClearance is a value to inflate shapes.
-     * @param aIncludeText = True to transform text shapes
+     * @param aError is the maximum error between true arc and polygon approximation.
-     * @param aIncludeShapes = True to transform footprint shapes
+     * @param aIncludeText set to true to transform text shapes.
+     * @param aIncludeShapes set to true to transform footprint shapes.
      */
     void TransformFPShapesWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer,
                                                   PCB_LAYER_ID aLayer, int aClearance,
@@ -394,9 +396,8 @@ public:
                                                   bool aIncludeShapes = true ) const;
 
     /**
-     * @brief TransformFPTextWithClearanceToPolygonSet
      * This function is the same as TransformGraphicShapesWithClearanceToPolygonSet
-     * but only generate text
+     * but only generate text.
      */
     void TransformFPTextWithClearanceToPolygonSet( SHAPE_POLY_SET& aCornerBuffer,
                                                    PCB_LAYER_ID aLayer, int aClearance,
@@ -413,20 +414,21 @@ public:
 
     /**
      * Resolve any references to system tokens supported by the component.
+     *
      * @param aDepth a counter to limit recursion and circular references.
      */
     bool ResolveTextVar( wxString* token, int aDepth = 0 ) const;
 
-    ///> @copydoc EDA_ITEM::GetMsgPanelInfo
+    ///< @copydoc EDA_ITEM::GetMsgPanelInfo
     void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
 
     bool HitTest( const wxPoint& aPosition, int aAccuracy = 0 ) const override;
 
     /**
-     * Tests if a point is inside the bounding polygon of the footprint
+     * Test if a point is inside the bounding polygon of the footprint.
      *
-     * The other hit test methods are just checking the bounding box, which
+     * The other hit test methods are just checking the bounding box, which can be quite
-     * can be quite inaccurate for rotated or oddly-shaped footprints.
+     * inaccurate for rotated or oddly-shaped footprints.
      *
      * @param aPosition is the point to test
      * @return true if aPosition is inside the bounding polygon
@@ -436,8 +438,7 @@ public:
     bool HitTest( const EDA_RECT& aRect, bool aContained, int aAccuracy = 0 ) const override;
 
     /**
-     * Function GetReference
+     * @return reference designator text.
-     * @return const wxString& - the reference designator text.
      */
     const wxString GetReference() const
     {
@@ -445,7 +446,6 @@ public:
     }
 
     /**
-     * Function SetReference
      * @param aReference A reference to a wxString object containing the reference designator
      *                   text.
      */
@@ -455,14 +455,12 @@ public:
     }
 
     /**
-     * Function IncrementReference
+     * Bump the current reference by \a aDelta.
-     * Bumps the current reference by aDelta.
      */
     void IncrementReference( int aDelta );
 
     /**
-     * Function GetValue
+     * @return the value text.
-     * @return const wxString& - the value text.
      */
     const wxString GetValue() const
     {
@@ -470,7 +468,6 @@ public:
     }
 
     /**
-     * Function SetValue
      * @param aValue A reference to a wxString object containing the value text.
      */
     void SetValue( const wxString& aValue )
@@ -490,29 +487,30 @@ public:
     void SetProperties( const std::map<wxString, wxString>& aProps ) { m_properties = aProps; }
 
     /**
-     * Function FindPadByName
+     * Return a #PAD with a matching name.
-     * returns a PAD* with a matching name.  Note that names may not be
+     *
-     * unique, depending on how the foot print was created.
+     * @note Names may not be unique depending on how the footprint was created.
-     * @param aPadName the pad name to find
+     *
-     * @return PAD* - The first matching name is returned, or NULL if not found.
+     * @param aPadName the pad name to find.
+     * @return the first matching named #PAD is returned or NULL if not found.
      */
     PAD* FindPadByName( const wxString& aPadName ) const;
 
     /**
-     * Function GetPad
+     * Get a pad at \a aPosition on \a aLayerMask in the footprint.
-     * get a pad at \a aPosition on \a aLayerMask in the footprint.
      *
      * @param aPosition A wxPoint object containing the position to hit test.
      * @param aLayerMask A layer or layers to mask the hit test.
-     * @return A pointer to a PAD object if found otherwise NULL.
+     * @return A pointer to a #PAD object if found otherwise NULL.
      */
     PAD* GetPad( const wxPoint& aPosition, LSET aLayerMask = LSET::AllLayersMask() );
 
     PAD* GetTopLeftPad();
 
     /**
-     * Gets the first pad in the list or NULL if none
+     * Get the first pad in the list or NULL if none.
-     * @return first pad or null pointer
+     *
+     * @return first pad or null pointer.
      */
     PAD* GetFirstPad() const
     {
@@ -520,8 +518,7 @@ public:
     }
 
     /**
-     * GetPadCount
+     * Return the number of pads.
-     * returns the number of pads.
      *
      * @param aIncludeNPTH includes non-plated through holes when true.  Does not include
      *                     non-plated through holes when false.
@@ -530,12 +527,10 @@ public:
     unsigned GetPadCount( INCLUDE_NPTH_T aIncludeNPTH = INCLUDE_NPTH_T(INCLUDE_NPTH) ) const;
 
     /**
-     * GetUniquePadCount
+     * Return the number of unique non-blank pads.
-     * returns the number of unique pads.
-     * A complex pad can be built with many pads having the same pad name
-     * to create a complex shape or fragmented solder paste areas.
      *
-     * GetUniquePadCount calculate the count of not blank pad names
+     * A complex pad can be built with many pads having the same pad name to create a complex
+     * shape or fragmented solder paste areas.
      *
      * @param aIncludeNPTH includes non-plated through holes when true.  Does not include
      *                     non-plated through holes when false.
@@ -544,8 +539,7 @@ public:
     unsigned GetUniquePadCount( INCLUDE_NPTH_T aIncludeNPTH = INCLUDE_NPTH_T(INCLUDE_NPTH) ) const;
 
     /**
-     * Function GetNextPadName
+     * Return the next available pad name in the footprint.
-     * returns the next available pad name in the footprint
      *
      * @param aFillSequenceGaps true if the numbering should "fill in" gaps in the sequence,
      *                          else return the highest value + 1
@@ -567,15 +561,14 @@ public:
     BOARD_ITEM* Duplicate() const override;
 
     /**
-     * Function DuplicateItem
+     * Duplicate a given item within the footprint, optionally adding it to the board.
-     * Duplicate a given item within the footprint, optionally adding it to the board
+     *
-     * @return the new item, or NULL if the item could not be duplicated
+     * @return the new item, or NULL if the item could not be duplicated.
      */
     BOARD_ITEM* DuplicateItem( const BOARD_ITEM* aItem, bool aAddToFootprint = false );
 
     /**
-     * Function Add3DModel
+     * Add \a a3DModel definition to the end of the 3D model list.
-     * adds \a a3DModel definition to the end of the 3D model list.
      *
      * @param a3DModel A pointer to a #FP_3DMODEL to add to the list.
      */
@@ -595,20 +588,20 @@ public:
     EDA_ITEM* Clone() const override;
 
     /**
-     * Function RunOnChildren
+     * Invoke a function on all BOARD_ITEMs that belong to the footprint (pads, drawings, texts).
+     *
+     * @note This function should not add or remove items to the footprint.
      *
-     * Invokes a function on all BOARD_ITEMs that belong to the footprint (pads, drawings, texts).
-     * Note that this function should not add or remove items to the footprint
      * @param aFunction is the function to be invoked.
      */
     void RunOnChildren( const std::function<void (BOARD_ITEM*)>& aFunction ) const;
 
     /**
-     * Returns a set of all layers that this footprint has drawings on similar to ViewGetLayers()
+     * Return a set of all layers that this footprint has drawings on similar to ViewGetLayers().
      *
-     * @param aLayers is an array to store layer ids
+     * @param aLayers is an array to store layer ids.
-     * @param aCount is the number of layers stored in the array
+     * @param aCount is the number of layers stored in the array.
-     * @param aIncludePads controls whether to also include pad layers
+     * @param aIncludePads controls whether to also include pad layers.
      */
     void GetAllDrawingLayers( int aLayers[], int& aCount, bool aIncludePads = true ) const;
 
@@ -619,35 +612,36 @@ public:
     virtual const BOX2I ViewBBox() const override;
 
     /**
-     * static function IsLibNameValid
      * Test for validity of a name of a footprint to be used in a footprint library
-     * ( no spaces, dir separators ... )
+     * ( no spaces, dir separators ... ).
-     * @param aName = the name in library to validate
+     *
+     * @param aName is the name in library to validate.
      * @return true if the given name is valid
      */
     static bool IsLibNameValid( const wxString& aName );
 
     /**
-     * static function StringLibNameInvalidChars
+     * Test for validity of the name in a library of the footprint ( no spaces, dir
-     * Test for validity of the name in a library of the footprint
+     * separators ... ).
-     * ( no spaces, dir separators ... )
+     *
-     * @param aUserReadable = false to get the list of invalid chars
+     * @param aUserReadable set to false to get the list of invalid characters or  true to get
-     *        true to get a readable form (i.e ' ' = 'space' '\\t'= 'tab')
+     *                      a readable form (i.e ' ' = 'space' '\\t'= 'tab').
-     * @return a constant std::string giving the list of invalid chars in lib name
+     *
+     * @return the list of invalid chars in the library name.
      */
     static const wxChar* StringLibNameInvalidChars( bool aUserReadable );
 
     /**
-     * Function SetInitialComments
+     * Take ownership of caller's heap allocated aInitialComments block.
-     * takes ownership of caller's heap allocated aInitialComments block.  The comments
+     *
-     * are single line strings already containing the s-expression comments with optional
+     * The comments are single line strings already containing the s-expression comments with
-     * leading whitespace and then a '#' character followed by optional single line text
+     * optional leading whitespace and then a '#' character followed by optional single line
-     * (text with no line endings, not even one).
+     * text (text with no line endings, not even one).  This block of single line comments
-     * This block of single line comments will be output upfront of any generated
+     * will be output upfront of any generated s-expression text in the PCBIO::Format() function.
-     * s-expression text in the PCBIO::Format() function.
+     *
-     * <p>
+     * @note A block of single line comments constitutes a multiline block of single line
-     * Note that a block of single line comments constitutes a multiline block of single
+     *       comments.  That is, the block is made of consecutive single line comments.
-     * line comments.  That is, the block is made of consecutive single line comments.
+     *
      * @param aInitialComments is a heap allocated wxArrayString or NULL, which the caller
      *                         gives up ownership of over to this FOOTPRINT.
      */
@@ -658,28 +652,31 @@ public:
     }
 
     /**
-     * Function CoverageRatio
+     * Calculate the ratio of total area of the footprint pads and graphical items to the
-     * Calculates the ratio of total area of the footprint pads and graphical items
+     * area of the footprint. Used by selection tool heuristics.
-     * to the area of the footprint. Used by selection tool heuristics.
+     *
-     * @return the ratio
+     * @return the ratio.
      */
     double CoverageRatio( const GENERAL_COLLECTOR& aCollector ) const;
 
     static double GetCoverageArea( const BOARD_ITEM* aItem, const GENERAL_COLLECTOR& aCollector );
 
-    /// Return the initial comments block or NULL if none, without transfer of ownership.
+    ///< Return the initial comments block or NULL if none, without transfer of ownership.
     const wxArrayString* GetInitialComments() const { return m_initial_comments; }
 
-    /** Used in DRC to test the courtyard area (a complex polygon)
+    /**
-     * @return the courtyard polygon
+     * Used in DRC to test the courtyard area (a complex polygon).
+     *
+     * @return the courtyard polygon.
      */
     SHAPE_POLY_SET& GetPolyCourtyardFront() { return m_poly_courtyard_front; }
     SHAPE_POLY_SET& GetPolyCourtyardBack() { return m_poly_courtyard_back; }
 
     /**
-     * Builds complex polygons of the courtyard areas from graphic items on the courtyard layers
+     * Build complex polygons of the courtyard areas from graphic items on the courtyard layers.
-     * @remark sets the MALFORMED_F_COURTYARD and MALFORMED_B_COURTYARD status flags if the given
+     *
-     *         courtyard layer does not contain a (single) closed shape
+     * @note Set the #MALFORMED_F_COURTYARD and #MALFORMED_B_COURTYARD status flags if the given
+     *       courtyard layer does not contain a (single) closed shape.
      */
     void BuildPolyCourtyards( OUTLINE_ERROR_HANDLER* aErrorHandler = nullptr );
 

pcbnew/footprint_edit_frame.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -37,29 +37,16 @@ namespace PCB { struct IFACE; }     // A KIFACE_I coded in pcbnew.c
 
 class FOOTPRINT_EDIT_FRAME : public PCB_BASE_EDIT_FRAME
 {
-    friend struct PCB::IFACE;
-
-    FOOTPRINT_TREE_PANE*        m_treePane;
-
-    wxObjectDataPtr<LIB_TREE_MODEL_ADAPTER> m_adapter;
-
-    std::unique_ptr<FOOTPRINT>  m_revertModule;
-    wxString                    m_footprintNameWhenLoaded;
-
-    int                         m_defaultLibWidth;
-
 public:
-
     ~FOOTPRINT_EDIT_FRAME();
 
     /**
-     * Function GetFootprintEditorFrameName (static)
+     * @return the frame name used when creating the frame used to get a reference to this
-     * @return the frame name used when creating the frame
+     *         frame, if exists
-     * used to get a reference to this frame, if exists
      */
     static const wxChar* GetFootprintEditorFrameName();
 
-    ///> @copydoc PCB_BASE_FRAME::GetModel()
+    ///< @copydoc PCB_BASE_FRAME::GetModel()
     BOARD_ITEM_CONTAINER* GetModel() const override;
     SELECTION&            GetCurrentSelection() override;
 
@@ -96,14 +83,15 @@ public:
     void OnExitKiCad( wxCommandEvent& aEvent );
 
     /**
-     * switches currently used canvas (Cairo / OpenGL).
+     * Switch the currently used canvas (Cairo / OpenGL).
-     * It also reinit the layers manager that slightly changes with canvases
+     *
+     * It also reinitializes the layer manager that slightly changes with canvases.
      */
     void SwitchCanvas( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ) override;
 
     /**
-     * Update the layer manager and other widgets from the board setup
+     * Update the layer manager and other widgets from the board setup (layer and items
-     * (layer and items visibility, colors ...)
+     * visibility, colors ...).
      */
     void UpdateUserInterface();
 
@@ -126,11 +114,12 @@ public:
     void ReCreateMenuBar() override;
 
     /**
-     * Re create the layer Box by clearing the old list, and building
+     * Re create the layer Box by clearing the old list, and building a new one from the new
-     * le new one, from the new layers names and cole layers
+     * layers names and layer colors..
-     * @param aForceResizeToolbar = true to resize the parent toolbar
+     *
-     * false if not needed (mainly in parent toolbar creation,
+     * @param aForceResizeToolbar true to resize the parent toolbar or false if not needed
-     * or when the layers names are not modified)
+     *                            (mainly in parent toolbar creation or when the layers names
+     *                            are not modified).
      */
     void ReCreateLayerBox( bool aForceResizeToolbar = true );
 
@@ -138,7 +127,7 @@ public:
 
     void SelectLayer( wxCommandEvent& event );
 
-    // The Tool Framework initalization, for GAL mode
+    // The Tool Framework initialization, for GAL mode
     void setupTools();
 
     void OnSaveFootprintAsPng( wxCommandEvent& event );
@@ -149,8 +138,9 @@ public:
     /**
      * Save a library to a new name and/or library type.
      *
+     * @see #PLUGIN::FootprintSave and #PLUGIN::FootprintLibCreate
+     *
      * @note Saving as a new library type requires the plug-in to support saving libraries
-     * @see PLUGIN::FootprintSave and PLUGIN::FootprintLibCreate
      */
     bool SaveLibraryAs( const wxString& aLibraryPath );
 
@@ -158,7 +148,7 @@ public:
     void OnUpdateLoadFootprintFromBoard( wxUpdateUIEvent& aEvent );
     void OnUpdateSaveFootprintToBoard( wxUpdateUIEvent& aEvent );
 
-    ///> @copydoc PCB_BASE_EDIT_FRAME::OnEditItemRequest()
+    ///< @copydoc PCB_BASE_EDIT_FRAME::OnEditItemRequest()
     void OnEditItemRequest( BOARD_ITEM* aItem ) override;
 
     /**
@@ -171,7 +161,7 @@ public:
     void LoadFootprintFromLibrary( LIB_ID aFPID );
 
     /**
-     * Returns the adapter object that provides the stored data.
+     * Return the adapter object that provides the stored data.
      */
     wxObjectDataPtr<LIB_TREE_MODEL_ADAPTER>& GetLibTreeAdapter() { return m_adapter; }
 
@@ -188,15 +178,13 @@ public:
     bool RevertFootprint();
 
     /**
-     * Must be called after a footprint change
+     * Must be called after a footprint change in order to set the "modify" flag of the
-     * in order to set the "modify" flag of the current screen
+     * current screen and prepare, if needed the refresh of the 3D frame showing the footprint.
-     * and prepare, if needed the refresh of the 3D frame showing the footprint
+     *
-     * do not forget to call the basic OnModify function to update auxiliary info
+     * Do not forget to call the basic OnModify function to update auxiliary info.
      */
     void OnModify() override;
 
-    // BOARD handling
-
     /**
      * Delete all and reinitialize the current board.
      *
@@ -218,7 +206,6 @@ public:
 
     void ClearModify();
 
-    // importing / exporting Footprint
     /**
      * Create a file containing only one footprint.
      */
@@ -258,25 +245,25 @@ public:
      */
     COLOR4D GetGridColor() override;
 
-    ///> @copydoc PCB_BASE_FRAME::SetActiveLayer()
+    ///< @copydoc PCB_BASE_FRAME::SetActiveLayer()
     void SetActiveLayer( PCB_LAYER_ID aLayer ) override;
 
-    ///> @copydoc PCB_BASE_FRAME::OnUpdateLayerAlpha()
+    ///< @copydoc PCB_BASE_FRAME::OnUpdateLayerAlpha()
     void OnUpdateLayerAlpha( wxUpdateUIEvent& aEvent ) override;
 
     void OnDisplayOptionsChanged() override;
 
-    ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas()
+    ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas()
     void ActivateGalCanvas() override;
 
     /**
      * Load a KiCad board (.kicad_pcb) from \a aFileName.
      *
-     * @param aFileSet - hold the BOARD file to load, a vector of one element.
+     * @param aFileSet is the BOARD file to load, a vector of one element.
-     * @param aCtl      - KICTL_ bits, one to indicate that an append of the board file
+     * @param aCtl is the KICTL_ bits, one to indicate that an append of the board file
-     *                      aFileName to the currently loaded file is desired.
+     *             \a  aFileName to the currently loaded file is desired.  @see #KIWAY_PLAYER
-     *                    @see #KIWAY_PLAYER for bit defines.
+     *             for bit defines.
-     * @return bool - false if file load fails, otherwise true.
+     * @return false if file load fails, otherwise true.
      */
     bool OpenProjectFiles( const std::vector<wxString>& aFileSet, int aCtl = 0 ) override;
 
@@ -287,7 +274,7 @@ public:
     void AddFootprintToBoard( FOOTPRINT* aFootprint ) override;
 
     /**
-     * Allows Footprint Editor to install its preferences panel into the preferences dialog.
+     * Allow footprint editor to install its preferences panel into the preferences dialog.
      */
     void InstallPreferences( PAGED_DIALOG* aParent, PANEL_HOTKEYS_EDITOR* aHotkeysPanel ) override;
 
@@ -304,7 +291,6 @@ public:
     /**
      * Synchronize the footprint library tree to the current state of the footprint library
      * table.
-     * @param aProgress
      */
     void SyncLibraryTree( bool aProgress );
 
@@ -316,7 +302,7 @@ public:
 
     void RefreshLibraryTree();
 
-    /// Reloads displayed items and sets view.
+    ///< Reload displayed items and sets view.
     void UpdateView();
 
     void FocusOnLibID( const LIB_ID& aLibID );
@@ -353,6 +339,19 @@ protected:
     void editFootprintProperties( FOOTPRINT* aFootprint );
 
     void setupUIConditions() override;
+
+private:
+    friend struct PCB::IFACE;
+
+    FOOTPRINT_TREE_PANE*        m_treePane;
+
+    wxObjectDataPtr<LIB_TREE_MODEL_ADAPTER> m_adapter;
+
+    std::unique_ptr<FOOTPRINT>  m_revertModule;
+    wxString                    m_footprintNameWhenLoaded;
+
+    int                         m_defaultLibWidth;
+
 };
 
 #endif      // FOOTPRINT_EDIT_FRAME_H

pcbnew/footprint_viewer_frame.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2018 Jean-Pierre Charras, jap.charras at wanadoo.fr
- * Copyright (C) 2004-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2004-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -43,20 +43,10 @@ namespace PCB { struct IFACE; }
  */
 class FOOTPRINT_VIEWER_FRAME : public PCB_BASE_FRAME
 {
-    friend struct PCB::IFACE;       // constructor called from here only
-
-protected:
-    FOOTPRINT_VIEWER_FRAME( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType );
-
-    MAGNETIC_SETTINGS m_magneticItems;
-
-    void setupUIConditions() override;
-
-
 public:
     ~FOOTPRINT_VIEWER_FRAME();
 
-    ///> @copydoc PCB_BASE_FRAME::GetModel()
+    ///< @copydoc PCB_BASE_FRAME::GetModel()
     BOARD_ITEM_CONTAINER* GetModel() const override;
 
     SELECTION& GetCurrentSelection() override;
@@ -72,22 +62,20 @@ public:
     }
 
     /**
-     * Function ReCreateLibraryList
+     * Create or recreate the list of current loaded libraries.
      *
-     * Creates or recreates the list of current loaded libraries.
      * This list is sorted, with the library cache always at end of the list
      */
     void ReCreateLibraryList();
 
     /**
-     * Update the ID_ADD_FOOTPRINT_TO_BOARD tool state in main toolbar
+     * Update the ID_ADD_FOOTPRINT_TO_BOARD tool state in main toolbar.
      */
     void OnUpdateFootprintButton(  wxUpdateUIEvent& aEvent );
 
     /**
-     * Function ShowModal
+     * Run the footprint viewer as a modal dialog.
      *
-     * Runs the Footprint Viewer as a modal dialog.
      * @param aFootprint an optional FPID string to initialize the viewer with and to
      *                   return a selected footprint through.
      */
@@ -95,15 +83,14 @@ public:
 
     COLOR_SETTINGS* GetColorSettings() const override;
 
+protected:
+    FOOTPRINT_VIEWER_FRAME( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType );
+
+    MAGNETIC_SETTINGS m_magneticItems;
+
+    void setupUIConditions() override;
+
 private:
-    wxTextCtrl*         m_libFilter;
-    wxListBox*          m_libList;        // The list of libs names
-    wxTextCtrl*         m_fpFilter;
-    wxListBox*          m_fpList;         // The list of footprint names
-
-    bool                m_autoZoom;
-    double              m_lastZoom;
-
     const wxString      getCurNickname();
     void                setCurNickname( const wxString& aNickname );
 
@@ -116,8 +103,7 @@ private:
     void OnIterateFootprintList( wxCommandEvent& event );
 
     /**
-     * Function UpdateTitle
+     * Update the window title with current library information.
-     * updates the window title with current library information.
      */
     void UpdateTitle();
 
@@ -148,45 +134,51 @@ private:
     void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged ) override;
 
     /**
-     * Function OnActivate
+     * Called when the frame frame is activate to reload the libraries and component lists
-     * is called when the frame frame is activate to reload the libraries and component lists
      * that can be changed by the schematic editor or the library editor.
      */
     void OnActivate( wxActivateEvent& event );
 
     /**
-     * Function AddFootprintToPCB
+     * Export the current footprint name and close the library browser.
-     * exports the current footprint name and close the library browser.
      */
     void AddFootprintToPCB( wxCommandEvent& aEvent );
 
     /**
-     * Function SelectAndViewFootprint
+     * Select and load the next or the previous footprint.
-     * Select and load the next or the previous footprint
+     *
-     * if no current footprint, Rebuild the list of footprints available in a given footprint
+     * If no current footprint, rebuild the list of footprints available in a given footprint
-     * library
+     * library.
-     * @param aMode = NEXT_PART or PREVIOUS_PART
+     *
+     * @param aMode #NEXT_PART or #PREVIOUS_PART.
      */
     void SelectAndViewFootprint( int aMode );
 
     /**
-     * Function Update3DView
-     * must be called after a footprint selection
      * Updates the 3D view and 3D frame title.
-     * @param aForceReload = true to reload data immediately
+     *
+     * Must be called after a footprint selection.
+     *
+     * @param aForceReload true to reload data immediately.
      */
     void Update3DView( bool aForceReload, const wxString* aTitle = nullptr ) override;
 
-    /*
-     * Virtual functions, not used here, but needed by PCB_BASE_FRAME
-     * (virtual pure functions )
-     */
     void SaveCopyInUndoList( EDA_ITEM*, UNDO_REDO, const wxPoint& ) override {}
     void SaveCopyInUndoList( const PICKED_ITEMS_LIST&, UNDO_REDO, const wxPoint &) override {}
 
     void updateView();
 
     DECLARE_EVENT_TABLE()
+
+    friend struct PCB::IFACE;       // constructor called from here only
+
+    wxTextCtrl*         m_libFilter;
+    wxListBox*          m_libList;        // The list of library names.
+    wxTextCtrl*         m_fpFilter;
+    wxListBox*          m_fpList;         // The list of footprint names.
+
+    bool                m_autoZoom;
+    double              m_lastZoom;
 };
 
 #endif  // FOOTPRINT_VIEWER_FRAME_H

pcbnew/footprint_wizard_frame.h

@@ -3,7 +3,7 @@
  *
  * Copyright (C) 2012 Miguel Angel Ajo Pelayo, miguelangel@nbee.es
  * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
- * Copyright (C) 2004-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2004-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -58,8 +58,8 @@ private:
     wxListBox*      m_pageList;             ///< The list of pages
     WX_GRID*        m_parameterGrid;        ///< The list of parameters
     int             m_parameterGridPage;    ///< the page currently displayed by m_parameterGrid
-                                            ///< it is most of time the m_pageList selection, but can differ
+                                            ///< it is most of time the m_pageList selection, but
-                                            ///< during transitions between pages.
+                                            ///< can differ during transitions between pages.
     wxTextCtrl*     m_buildMessageBox;
 
     wxString        m_auiPerspective;       ///< Encoded string describing the AUI layout
@@ -77,7 +77,7 @@ public:
 
     ~FOOTPRINT_WIZARD_FRAME();
 
-    ///> @copydoc PCB_BASE_FRAME::GetModel()
+    ///< @copydoc PCB_BASE_FRAME::GetModel()
     BOARD_ITEM_CONTAINER* GetModel() const override;
 
     FOOTPRINT* GetBuiltFootprint();
@@ -97,90 +97,78 @@ private:
     void                OnGridSize( wxSizeEvent& aSizeEvent );
 
     /**
-     * redraws the message panel.
+     * Redraw the message panel.
-     * display the current footprint info, or
+     *
-     * clear the message panel if nothing is loaded
+     * Display the current footprint info, or clear the message panel if nothing is loaded.
      */
     void UpdateMsgPanel() override;
 
     /**
-     * rebuild the GAL view (reint tool manager, colors and drawings)
+     * Rebuild the GAL view (reint tool manager, colors and drawings) must be run after any
-     * must be run after any footprint change.
+     * footprint change.
      */
     void updateView();
 
     /**
-     * Function ExportSelectedFootprint();
+     * Will let the caller exit from the wait loop, and get the built footprint.
-     * will let the caller exit from the wait loop, and get the built footprint
      *
      */
     void ExportSelectedFootprint( wxCommandEvent& aEvent );
 
     /**
-     * Function OnSashDrag
+     * Resize the child windows when dragging a sash window border.
-     * resizes the child windows when dragging a sash window border.
      */
-
     void OnSashDrag( wxSashEvent& event );
 
     /**
-     * Function ReCreatePageList
+     * Create or recreate the list of parameter pages for the current wizard.
-     * Creates or recreates the list of parameter pages for the current wizard.
+     *
      * This list is sorted
      */
     void ReCreatePageList();
 
     /**
-     * Function ReCreateParameterList
+     * Create the list of parameters for the current page.
-     * Creates the list of parameters for the current page
      */
     void ReCreateParameterList();
 
     /**
-     * Expand the 'Value' column to fill available
+     * Expand the 'Value' column to fill available.
      */
     void ResizeParamColumns();
 
     /**
-     * Function initParameterGrid
+     * Prepare the grid where parameters are displayed.
-     * Prepare the grid where parameters are displayed
      */
     void initParameterGrid();
 
     /**
-     * Function SelectFootprintWizard
+     * Show the list of footprint wizards available into the system.
-     * Shows the list of footprint wizards available into the system
      */
     void SelectFootprintWizard();
 
     /**
-     * Function ReloadFootprint
+     * Reload the current footprint.
-     * Reloads the current footprint
      */
     void ReloadFootprint();
 
     /**
-     * Function DisplayBuildMessages
+     * Display the message generated by the python build footprint script.
-     * Display the message generated by the python build footprint script
      */
     void DisplayBuildMessage( wxString& aMessage );
 
     /**
-     * Function GetMyWizard
+     * Reloads the wizard by name.
-     * Reloads the wizard by name
      */
     FOOTPRINT_WIZARD* GetMyWizard();
 
-
     void Process_Special_Functions( wxCommandEvent& event );
 
     /**
-     * Function DisplayWizardInfos
+     * Show all the details about the current wizard.
-     * Shows all the details about the current wizard
      */
     void DisplayWizardInfos();
 
-
     void doCloseWindow() override;
     void ReCreateHToolbar() override;
     void ReCreateVToolbar() override;
@@ -192,8 +180,7 @@ private:
     WINDOW_SETTINGS* GetWindowSettings( APP_SETTINGS_BASE* aCfg ) override;
 
     /**
-             * Function OnActivate
+     * Called when the frame frame is activate to reload the libraries and component lists
-             * is called when the frame frame is activate to reload the libraries and component lists
      * that can be changed by the schematic editor or the library editor.
      */
     void OnActivate( wxActivateEvent& event );
@@ -203,23 +190,22 @@ private:
     void DefaultParameters( wxCommandEvent& event );
 
     /**
-     * Function ParametersUpdated
+     * Update the footprint python parameters values from the values in grid.
-     * Update the footprint python parameters values from the values in grid
      */
     void ParametersUpdated( wxGridEvent& event );
 
     /**
-     * Function Update3D_Frame
+     * Must be called after a footprint selection.
-     * must be called after a footprint selection
+     *
      * Updates the 3D view and 3D frame title.
-     * @param aForceReload = true to reload data immediately
+     *
-     * @param aTitle (optional) the window title to set for the viewer
+     * @param aForceReload true to reload data immediately.
+     * @param aTitle (optional) the window title to set for the viewer.
      */
     void Update3DView( bool aForceReload, const wxString* aTitle ) override;
 
     /*
-     * Virtual functions, not used here, but needed by PCB_BASE_EDIT_FRAME
+     * Not used here but needed by PCB_BASE_EDIT_FRAME.
-     * (virtual pure functions )
      */
     void SaveCopyInUndoList( EDA_ITEM*, UNDO_REDO, const wxPoint& ) override {}
     void SaveCopyInUndoList( const PICKED_ITEMS_LIST&, UNDO_REDO, const wxPoint& ) override {}

pcbnew/fp_text.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2004 Jean-Pierre Charras, jaen-pierre.charras@gipsa-lab.inpg.com
- * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -102,8 +102,8 @@ public:
     void KeepUpright( double aOldOrientation, double aNewOrientation );
 
     /**
-     * @return force the text rotation to be always between -90 .. 90 deg. Otherwise the text is not easy to read
+     * @return force the text rotation to be always between -90 .. 90 deg. Otherwise the text
-     * if false, the text rotation is free.
+     *         is not easy to read if false, the text rotation is free.
      */
     bool IsKeepUpright() const
     {
@@ -139,8 +139,7 @@ public:
     TEXT_TYPE GetType() const           { return m_Type; }
 
     /**
-     * Function SetEffects
+     * Set the text effects from another instance.
-     * sets the text effects from another instance.
      */
     void SetEffects( const FP_TEXT& aSrc )
     {
@@ -150,8 +149,7 @@ public:
     }
 
     /**
-     * Function SwapEffects
+     * Swap the text effects of the two involved instances.
-     * swaps the text effects of the two involved instances.
      */
     void SwapEffects( FP_TEXT& aTradingPartner )
     {
@@ -161,15 +159,15 @@ public:
         // std::swap( m_Type, aTradingPartner.m_Type );
     }
 
-    // The Pos0 accessors are for footprint-relative coordinates
+    // The Pos0 accessors are for footprint-relative coordinates.
     void SetPos0( const wxPoint& aPos ) { m_Pos0 = aPos; SetDrawCoord(); }
     const wxPoint& GetPos0() const      { return m_Pos0; }
 
     int GetLength() const;        // text length
 
     /**
-     * @return the text rotation for drawings and plotting
+     * @return the text rotation for drawings and plotting the footprint rotation is taken
-     * the footprint rotation is taken in account
+     *         in account.
      */
     virtual double GetDrawRotation() const override;
     double GetDrawRotationRadians() const { return GetDrawRotation() * M_PI/1800; }
@@ -177,10 +175,10 @@ public:
     // Virtual function
     const EDA_RECT GetBoundingBox() const override;
 
-    ///> Set absolute coordinates.
+    ///< Set absolute coordinates.
     void SetDrawCoord();
 
-    ///> Set relative coordinates.
+    ///< Set relative coordinates.
     void SetLocalCoord();
 
     void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;

pcbnew/import_gfx/graphics_import_mgr.h

@@ -2,8 +2,9 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2016 CERN
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
- * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -33,12 +34,12 @@ class GRAPHICS_IMPORT_PLUGIN;
 class wxString;
 
 /**
- * @brief Class to manage vector graphics importers.
+ * Manage vector graphics importers.
  */
 class GRAPHICS_IMPORT_MGR
 {
 public:
-    ///> List of handled file types.
+    ///< List of handled file types.
     enum GFX_FILE_T
     {
         DXF,
@@ -54,16 +55,16 @@ public:
      */
     GRAPHICS_IMPORT_MGR( const TYPE_LIST& aBlacklist );
 
-    ///> Vector containing all GFX_FILE_T values that can be imported.
+    ///< Vector containing all GFX_FILE_T values that can be imported.
     TYPE_LIST GetImportableFileTypes() const
     {
         return m_importableTypes;
     }
 
-    ///> Returns a plugin that handles a specific file extension.
+    ///< Returns a plugin that handles a specific file extension.
     std::unique_ptr<GRAPHICS_IMPORT_PLUGIN> GetPluginByExt( const wxString& aExtension ) const;
 
-    ///> Returns a plugin instance for a specific file type.
+    ///< Returns a plugin instance for a specific file type.
     std::unique_ptr<GRAPHICS_IMPORT_PLUGIN> GetPlugin( GFX_FILE_T aType ) const;
 
 private:

pcbnew/import_gfx/graphics_import_plugin.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2016 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -121,7 +122,7 @@ public:
     const virtual std::string& GetMessages() const = 0;
 
 protected:
-    ///> Importer used to create objects representing the imported shapes.
+    ///< Importer used to create objects representing the imported shapes.
     GRAPHICS_IMPORTER* m_importer;
 };
 

pcbnew/import_gfx/graphics_importer.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2016 CERN
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -109,7 +110,7 @@ public:
     }
 
     /**
-     * Sets the line width for the imported outlines (in mm).
+     * Set the line width for the imported outlines (in mm).
      */
     void SetLineWidthMM( double aWidth )
     {
@@ -117,7 +118,7 @@ public:
     }
 
     /**
-     * Returns the line width used for importing the outlines (in mm).
+     * Return the line width used for importing the outlines (in mm).
      */
     double GetLineWidthMM() const
     {
@@ -133,8 +134,7 @@ public:
     }
 
     /**
-     * @return the offset to add to coordinates when importing graphic items.
+     * @return the offset in millimeters to add to coordinates when importing graphic items.
-     * The offset is always in mm
      */
     const VECTOR2D& GetImportOffsetMM() const
     {
@@ -142,8 +142,7 @@ public:
     }
 
     /**
-     * Set the offset to add to coordinates when importing graphic items.
+     * Set the offset in millimeters to add to coordinates when importing graphic items.
-     * The offset is always in mm
      */
     void SetImportOffsetMM( const VECTOR2D& aOffset )
     {
@@ -152,7 +151,8 @@ public:
 
     /**
      * Set the scale factor affecting the imported shapes.
-     * it allows conversion between imported shapes units and mm
+     *
+     * This allows conversion between imported shapes units and millimeters.
      */
     void SetScale( double aScale )
     {
@@ -183,11 +183,9 @@ public:
         return m_items;
     }
 
-    ///> Default line thickness (in mm)
+    ///< Default line thickness (in mm)
     static constexpr unsigned int DEFAULT_LINE_WIDTH_DFX = 1;
 
-    // Methods to be implemented by derived graphics importers
-
     /**
      * Create an object representing a line segment.
      *
@@ -204,7 +202,8 @@ public:
      * @param aRadius is the circle radius expressed in mm.
      * @param aWidth is the segment thickness in mm. Use -1 for default line thickness
      */
-    virtual void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth, bool aFilled ) = 0;
+    virtual void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth,
+                            bool aFilled ) = 0;
 
     /**
      * Create an object representing an arc.
@@ -250,23 +249,23 @@ public:
                             double aWidth ) = 0;
 
 protected:
-    ///> Adds an item to the imported shapes list.
+    ///< Add an item to the imported shapes list.
     void addItem( std::unique_ptr<EDA_ITEM> aItem )
     {
         m_items.emplace_back( std::move( aItem ) );
     }
 
 private:
-    ///> List of imported items
+    ///< List of imported items
     std::list<std::unique_ptr<EDA_ITEM>> m_items;
 
-    ///> Plugin used to load a file
+    ///< Plugin used to load a file
     std::unique_ptr<GRAPHICS_IMPORT_PLUGIN> m_plugin;
 
-    ///> Total image width
+    ///< Total image width
     double m_originalWidth;
 
-    ///> Total image Height;
+    ///< Total image Height;
     double m_originalHeight;
 
     /**
@@ -276,14 +275,14 @@ private:
      */
     double m_scale;
 
-    ///> Default line thickness for the imported graphics
+    ///< Default line thickness for the imported graphics
     double m_lineWidth;
 
 protected:
-    ///> factor to convert millimeters to Internal Units
+    ///< factor to convert millimeters to Internal Units
     double m_millimeterToIu;
 
-    ///> Offset (in mm) for imported coordinates
+    ///< Offset (in mm) for imported coordinates
     VECTOR2D m_offsetCoordmm;
 };
 

pcbnew/import_gfx/graphics_importer_buffer.h

@@ -2,8 +2,9 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2017 CERN
+ * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Janito Vaqueiro Ferreira Filho <janito.vff@gmail.com>
- * Copyright (C) 2018-2019 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -323,7 +324,8 @@ public:
 
     void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth, bool aFilled ) override;
 
-    void AddArc( const VECTOR2D& aCenter, const VECTOR2D& aStart, double aAngle, double aWidth ) override;
+    void AddArc( const VECTOR2D& aCenter, const VECTOR2D& aStart, double aAngle,
+                 double aWidth ) override;
 
     void AddPolygon( const std::vector< VECTOR2D >& aVertices, double aWidth ) override;
 
@@ -343,7 +345,7 @@ public:
     }
 
 protected:
-    ///> List of imported shapes
+    ///< List of imported shapes
     std::list< std::unique_ptr< IMPORTED_SHAPE > > m_shapes;
 };
 

pcbnew/import_gfx/graphics_importer_pcbnew.h

@@ -2,8 +2,9 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2016 CERN
+ * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
- * Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -42,7 +43,8 @@ public:
     GRAPHICS_IMPORTER_PCBNEW();
 
     /**
-     * @brief Sets the target layer for the imported shapes.
+     * Set the target layer for the imported shapes.
+     *
      * @param aLayer is the layer to be used by the imported shapes.
      */
     void SetLayer( PCB_LAYER_ID aLayer )
@@ -51,7 +53,7 @@ public:
     }
 
     /**
-     * @brief Returns the target layer for the imported shapes.
+     * Return the target layer for the imported shapes.
      */
     PCB_LAYER_ID GetLayer() const
     {
@@ -72,30 +74,34 @@ public:
             EDA_TEXT_HJUSTIFY_T aHJustify, EDA_TEXT_VJUSTIFY_T aVJustify ) override;
 
     void AddSpline( const VECTOR2D& aStart, const VECTOR2D& aBezierControl1,
-                    const VECTOR2D& aBezierControl2, const VECTOR2D& aEnd , double aWidth ) override;
+                    const VECTOR2D& aBezierControl2, const VECTOR2D& aEnd,
+                    double aWidth ) override;
 
-    /** convert a imported coordinate to a board coordinate, according to
+    /**
-     * the internal units, the user scale and offset
+     * Convert an imported coordinate to a board coordinate, according to the internal units,
-     * @param aCoordinate is the imported coordinate in mm
+     * user scale and offset
+     *
+     * @param aCoordinate is the imported coordinate in mm.
      */
     wxPoint MapCoordinate( const VECTOR2D& aCoordinate );
 
-    /** @return a line thickness in a board Iu value, according to
+    /**
-     * the internal units.
+     * If aLineWidth < 0, the default line thickness value is returned.
-     * if aLineWidth < 0, the default ine thickness value is returned
+     *
-     * @param aLineWidth is the line thickness in mm to convert
+     * @param aLineWidth is the line thickness in mm to convert.
+     * @return a line thickness in a board Iu value, according to the internal units.
      */
     int MapLineWidth( double aLineWidth );
 
 protected:
-    ///> Create an object representing a graphical shape.
+    ///< Create an object representing a graphical shape.
     virtual std::unique_ptr<PCB_SHAPE> createDrawing() = 0;
 
-    ///> Create an object representing a text. Both pointers point to different parts of the
+    ///< Create an object representing a text. Both pointers point to different parts of the
-    ///> same object, the EDA_TEXT pointer is simply for convenience.
+    ///< same object, the EDA_TEXT pointer is simply for convenience.
     virtual std::pair<std::unique_ptr<BOARD_ITEM>, EDA_TEXT*> createText() = 0;
 
-    ///> Target layer for the imported shapes.
+    ///< Target layer for the imported shapes.
     PCB_LAYER_ID m_layer;
 };
 

pcbnew/microwave/microwave_tool.cpp

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017-2020 Kicad Developers, see change_log.txt for contributors.
+ * Copyright (C) 2017-2021 Kicad Developers, see change_log.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -101,8 +101,8 @@ static const COLOR4D inductorAreaFill( 0.3, 0.3, 0.5, 0.3 );
 static const COLOR4D inductorAreaStroke( 0.4, 1.0, 1.0, 1.0 );
 static const double  inductorAreaStrokeWidth = 1.0;
 
-///> Aspect of the preview rectangle - this is hardcoded in the
+///< Aspect of the preview rectangle - this is hardcoded in the
-///> microwave backend for now
+///< microwave backend for now
 static const double  inductorAreaAspect = 0.5;
 
 
@@ -245,7 +245,8 @@ void MICROWAVE_TOOL::setTransitions()
     Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateGap.MakeEvent() );
     Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateStub.MakeEvent() );
     Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateStubArc.MakeEvent() );
-    Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateFunctionShape.MakeEvent() );
+    Go( &MICROWAVE_TOOL::addMicrowaveFootprint,
+        PCB_ACTIONS::microwaveCreateFunctionShape.MakeEvent() );
 
     Go( &MICROWAVE_TOOL::drawMicrowaveInductor, PCB_ACTIONS::microwaveCreateLine.MakeEvent() );
 }

pcbnew/microwave/microwave_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -51,8 +51,6 @@ public:
 
 
 /**
- * MICROWAVE_TOOL
- *
  * Tool responsible for adding microwave features to PCBs
  */
 class MICROWAVE_TOOL : public PCB_TOOL_BASE
@@ -61,39 +59,41 @@ public:
     MICROWAVE_TOOL();
     ~MICROWAVE_TOOL();
 
-    ///> React to model/view changes
+    ///< React to model/view changes
     void Reset( RESET_REASON aReason ) override;
 
-    ///> Bind handlers to corresponding TOOL_ACTIONs
+    ///< Bind handlers to corresponding TOOL_ACTIONs
     void setTransitions() override;
 
 private:
-    ///> Main interactive tool
+    ///< Main interactive tool
     int addMicrowaveFootprint( const TOOL_EVENT& aEvent );
 
-    ///> Create an inductor between the two points
+    ///< Create an inductor between the two points
     void createInductorBetween( const VECTOR2I& aStart, const VECTOR2I& aEnd );
 
-    ///> Draw a microwave inductor interactively
+    ///< Draw a microwave inductor interactively
     int drawMicrowaveInductor( const TOOL_EVENT& aEvent );
 
     /**
-     * Creates a footprint "GAP" or "STUB" used in micro wave designs.
+     * Create a footprint "GAP" or "STUB" used in micro wave designs.
+     *
      * This footprint has 2 pads:
      * PAD_ATTRIB_SMD, rectangular, H size = V size = current track width.
      * the "gap" is isolation created between this 2 pads
      *
-     * @param aComponentShape is the component to create
+     * @param aComponentShape is the component to create.
-     * @return the new footprint
+     * @return the new footprint.
      */
     FOOTPRINT* createFootprint( MICROWAVE_FOOTPRINT_SHAPE aFootprintShape );
 
     FOOTPRINT* createPolygonShape();
 
     /**
-     * Creates an S-shaped coil footprint for microwave applications.
+     * Create an S-shaped coil footprint for microwave applications.
      */
-    FOOTPRINT* createMicrowaveInductor( MICROWAVE_INDUCTOR_PATTERN& aPattern, wxString& aErrorMessage );
+    FOOTPRINT* createMicrowaveInductor( MICROWAVE_INDUCTOR_PATTERN& aPattern,
+                                        wxString& aErrorMessage );
 
     /**
      * Create a basic footprint for micro wave applications.
@@ -101,10 +101,10 @@ private:
      * The default pad settings are:
      *  PAD_ATTRIB_SMD, rectangular, H size = V size = current track width.
      *
-     * @param aValue is the text value
+     * @param aValue is the text value.
-     * @param aTextSize is the size of ref and value texts ( <= 0 to use board default values )
+     * @param aTextSize is the size of ref and value texts ( <= 0 to use board default values ).
-     * @param aPadCount is number of pads
+     * @param aPadCount is number of pads.
-     * @return the new footprint
+     * @return the new footprint.
      */
     FOOTPRINT* createBaseFootprint( const wxString& aValue, int aTextSize, int aPadCount );
 };

pcbnew/netinfo.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2009 Jean-Pierre Charras, jp.charras at wanadoo.fr
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -59,26 +59,10 @@ class PCB_BASE_FRAME;
 DECL_VEC_FOR_SWIG( PADS_VEC, PAD* )
 
 /**
- * NETINFO_ITEM
+ * Handle the data for a net.
- * handles the data for a net
  */
 class NETINFO_ITEM : public BOARD_ITEM
 {
-    friend class NETINFO_LIST;
-
-private:
-    int         m_netCode;         ///< A number equivalent to the net name.
-    wxString    m_netname;         ///< Full net name like /sheet/subsheet/vout used by Eeschema.
-    wxString    m_shortNetname;    ///< short net name, like vout from /sheet/subsheet/vout.
-
-    NETCLASSPTR m_netClass;
-
-    bool        m_isCurrent;       ///< Indicates the net is currently in use.  We still store
-                                   ///< those that are not during a session for undo/redo and to
-                                   ///< keep netclass membership information.
-
-    BOARD*      m_parent;          ///< The parent board the net belongs to.
-
 public:
 
     NETINFO_ITEM( BOARD* aParent, const wxString& aNetName = wxEmptyString, int aNetCode = -1 );
@@ -113,9 +97,7 @@ public:
     void SetNetClass( const NETCLASSPTR& aNetClass );
 
     /**
-     * Function GetNetClass
+     * @note Do **not** return a std::shared_ptr from this.  It is used heavily in DRC, and the
-     *
-     * Note: do NOT return a std::shared_ptr from this.  It is used heavily in DRC, and the
      *       std::shared_ptr stuff shows up large in performance profiling.
      */
     NETCLASS* GetNetClass()
@@ -132,20 +114,17 @@ public:
     void SetNetCode( int aNetCode ) { m_netCode = aNetCode; }
 
     /**
-     * Function GetNetname
+     * @return the full netname.
-     * @return const wxString&, a reference to the full netname
      */
     const wxString& GetNetname() const { return m_netname; }
 
     /**
-     * Function GetShortNetname
+     * @return the short netname.
-     * @return const wxString &, a reference to the short netname
      */
     const wxString& GetShortNetname() const { return m_shortNetname; }
 
     /**
-     * Function SetNetname
+     * Set the long netname to \a aNetName, and the short netname to the last token in
-     * Sets the long netname to \a aNetName, and the short netname to the last token in
      * the long netname's path.
      */
     void SetNetname( const wxString& aNewName )
@@ -162,8 +141,7 @@ public:
     void SetIsCurrent( bool isCurrent ) { m_isCurrent = isCurrent; }
 
     /**
-     * Function GetMsgPanelInfo
+     * Return the information about the #NETINFO_ITEM in \a aList to display in the
-     * returns the information about the #NETINFO_ITEM in \a aList to display in the
      * message panel.
      *
      * @param aList is the list in which to place the  status information.
@@ -171,8 +149,7 @@ public:
     void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
 
     /**
-     * Function Clear
+     * Set all fields to their default values.
-     * sets all fields to their defaults values.
      */
     void Clear()
     {
@@ -183,6 +160,21 @@ public:
     {
         return m_parent;
     }
+
+private:
+    friend class NETINFO_LIST;
+
+    int         m_netCode;         ///< A number equivalent to the net name.
+    wxString    m_netname;         ///< Full net name like /sheet/subsheet/vout used by Eeschema.
+    wxString    m_shortNetname;    ///< short net name, like vout from /sheet/subsheet/vout.
+
+    NETCLASSPTR m_netClass;
+
+    bool        m_isCurrent;       ///< Indicates the net is currently in use.  We still store
+                                   ///< those that are not during a session for undo/redo and to
+                                   ///< keep netclass membership information.
+
+    BOARD*      m_parent;          ///< The parent board the net belongs to.
 };
 
 
@@ -196,8 +188,7 @@ public:
 
 
     /**
-     * Function SetBoard
+     * Set a BOARD object that is used to prepare the net code map.
-     * Sets a BOARD object that is used to prepare the net code map.
      */
     void SetBoard( const BOARD* aBoard )
     {
@@ -206,23 +197,24 @@ public:
     }
 
     /**
-     * Function Update
+     * Prepare a mapping for net codes so they can be saved as consecutive numbers.
-     * Prepares a mapping for net codes so they can be saved as consecutive numbers.
+     *
      * To retrieve a mapped net code, use translateNet() function after calling this.
      */
     void Update();
 
     /**
-     * Function Translate
+     * Translate net number according to the map prepared by Update() function.
-     * Translates net number according to the map prepared by Update() function. It
+     *
-     * allows one to have items stored with consecutive net codes.
+     * It allows one to have items stored with consecutive net codes.
+     *
      * @param aNetCode is an old net code.
      * @return Net code that follows the mapping.
      */
     int Translate( int aNetCode ) const;
 
-    ///> Wrapper class, so you can iterate through NETINFO_ITEM*s, not
+    ///< Wrapper class, so you can iterate through NETINFO_ITEM*s, not
-    ///> std::pair<int/wxString, NETINFO_ITEM*>
+    ///< std::pair<int/wxString, NETINFO_ITEM*>
     class iterator
     {
     public:
@@ -268,9 +260,9 @@ public:
     };
 
     /**
-     * Function begin()
+     * Return iterator to the first entry in the mapping.
-     * Returns iterator to the first entry in the mapping.
+     *
-     * NOTE: The entry is a pointer to the original NETINFO_ITEM object, this it contains
+     * @note The entry is a pointer to the original NETINFO_ITEM object, this it contains
      *       not mapped net code.
      */
     iterator begin() const
@@ -279,9 +271,9 @@ public:
     }
 
     /**
-     * Function end()
+     * Return iterator to the last entry in the mapping.
-     * Returns iterator to the last entry in the mapping.
+     *
-     * NOTE: The entry is a pointer to the original NETINFO_ITEM object, this it contains
+     * @note The entry is a pointer to the original NETINFO_ITEM object, this it contains
      *       not mapped net code.
      */
     iterator end() const
@@ -290,7 +282,6 @@ public:
     }
 
     /**
-     * Function GetSize
      * @return Number of mapped nets (i.e. not empty nets for a given BOARD object).
      */
     int GetSize() const
@@ -299,9 +290,9 @@ public:
     }
 
 private:
-    const BOARD*       m_board;         ///> Board for which mapping is prepared
+    const BOARD*       m_board;         ///< Board for which mapping is prepared
-    std::map<int, int> m_netMapping;    ///> Map that allows saving net codes with consecutive
+    std::map<int, int> m_netMapping;    ///< Map that allows saving net codes with consecutive
-                                        ///> numbers (for compatibility reasons)
+                                        ///< numbers (for compatibility reasons)
 };
 
 
@@ -319,9 +310,7 @@ DECL_MAP_FOR_SWIG( NETCODES_MAP, int,       NETINFO_ITEM* )
 #endif
 
 /**
- * NETINFO_LIST
+ * Container for #NETINFO_ITEM elements, which are the nets.
- * is a container class for NETINFO_ITEM elements, which are the nets.  That makes
- * this class a container for the nets.
  */
 class NETINFO_LIST
 {
@@ -332,43 +321,37 @@ public:
     ~NETINFO_LIST();
 
     /**
-     * Function GetItem
+     * @param aNetCode netcode to identify a given #NETINFO_ITEM.
-     * @param aNetCode = netcode to identify a given NETINFO_ITEM
+     * @return net item by \a aNetCode, or NULL if not found.
-     * @return NETINFO_ITEM* - by \a aNetCode, or NULL if not found
      */
     NETINFO_ITEM* GetNetItem( int aNetCode ) const;
 
     /**
-     * Function GetItem
+     * @param aNetName net name to identify a given #NETINFO_ITEM.
-     * @param aNetName = net name to identify a given NETINFO_ITEM
+     * @return net item by \a aNetName, or NULL if not found.
-     * @return NETINFO_ITEM* - by \a aNetName, or NULL if not found
      */
     NETINFO_ITEM* GetNetItem( const wxString& aNetName ) const;
 
     /**
-     * Function GetNetCount
+     * @return the number of nets ( always >= 1 ) because the first net is the "not connected"
-     * @return the number of nets ( always >= 1 )
+     *         net and always exists
-     * because the first net is the "not connected" net and always exists
      */
     unsigned GetNetCount() const { return m_netNames.size(); }
 
     /**
-     * Function AppendNet
+     * Add \a aNewElement to the end of the net list. Negative net code means it is going to be
-     * adds \a aNewElement to the end of the net list. Negative net code means it is going to be
      * auto-assigned.
      */
     void AppendNet( NETINFO_ITEM* aNewElement );
 
     /**
-     * Function RemoveNet
+     * Remove a net from the net list.
-     * Removes a new from the net list.
      */
     void RemoveNet( NETINFO_ITEM* aNet );
     void RemoveUnusedNets();
 
     /**
-     * Function GetPadCount
+     * @return the number of pads in board.
-     * @return the number of pads in board
      */
 
     /// Return the name map, at least for python.
@@ -377,16 +360,16 @@ public:
     /// Return the netcode map, at least for python.
     const NETCODES_MAP& NetsByNetcode() const   { return m_netCodes; }
 
-    ///> Constant that holds the "unconnected net" number (typically 0)
+    ///< Constant that holds the "unconnected net" number (typically 0)
-    ///> all items "connected" to this net are actually not connected items
+    ///< all items "connected" to this net are actually not connected items
     static const int UNCONNECTED;
 
-    ///> Constant that forces initialization of a netinfo item to the NETINFO_ITEM ORPHANED
+    ///< Constant that forces initialization of a netinfo item to the NETINFO_ITEM ORPHANED
-    ///> (typically -1) when calling SetNetCode od board connected items
+    ///< (typically -1) when calling SetNetCode on board connected items.
     static const int ORPHANED;
 
-    ///> NETINFO_ITEM meaning that there was no net assigned for an item, as there was no
+    ///< NETINFO_ITEM meaning that there was no net assigned for an item, as there was no
-    ///> board storing net list available.
+    ///< board storing net list available.
     static NETINFO_ITEM* OrphanedItem()
     {
         static NETINFO_ITEM* g_orphanedItem;
@@ -402,8 +385,8 @@ public:
 #endif
 
 #ifndef SWIG
-    ///> Wrapper class, so you can iterate through NETINFO_ITEM*s, not
+    ///< Wrapper class, so you can iterate through NETINFO_ITEM*s, not
-    ///> std::pair<int/wxString, NETINFO_ITEM*>
+    ///< std::pair<int/wxString, NETINFO_ITEM*>
     class iterator
     {
     public:
@@ -468,25 +451,22 @@ public:
 
 private:
     /**
-     * Function clear
+     * Delete the list of nets (and free memory).
-     * deletes the list of nets (and free memory)
      */
     void clear();
 
     /**
-     * Function buildListOfNets
+     * Rebuild the list of NETINFO_ITEMs
-     * builds or rebuilds the list of NETINFO_ITEMs
+     *
      * The list is sorted by names.
      */
     void buildListOfNets();
 
     /**
-     * Function getFreeNetCode
+     * Return the first available net code that is not used by any other net.
-     * returns the first available net code that is not used by any other net.
      */
     int getFreeNetCode();
 
-private:
     BOARD*       m_parent;
 
     NETNAMES_MAP m_netNames;        ///< map of <wxString, NETINFO_ITEM*>, is NETINFO_ITEM owner

pcbnew/netlist_reader/board_netlist_updater.h

@@ -11,7 +11,7 @@
  * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
  * Copyright (C) 2011 Wayne Stambaugh <stambaughw@verizon.net>
  *
- * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -44,8 +44,7 @@ class PCB_EDIT_FRAME;
 #include <board_commit.h>
 
 /**
- * BOARD_NETLIST_UPDATER
+ * Update the #BOARD with a new netlist.
- * updates the #BOARD with a new netlist.
  *
  * The changes are made to the board are as follows they are not disabled in the status
  * settings in the #NETLIST:
@@ -76,53 +75,53 @@ public:
     ~BOARD_NETLIST_UPDATER();
 
     /**
-     * Function UpdateNetlist()
+     * Update the board's components according to the new netlist.
+     *
+     * See #BOARD_NETLIST_UPDATER class description for the details of the process.
      *
-     * Updates the board's components according to the new netlist.
-     * See BOARD_NETLIST_UPDATER class description for the details of the process.
      * @param aNetlist the new netlist
      * @return true if process was completed successfully
      */
     bool UpdateNetlist( NETLIST& aNetlist );
 
-    ///> Sets the reporter object
+    ///< Set the reporter object.
     void SetReporter( REPORTER* aReporter )
     {
         m_reporter = aReporter;
     }
 
-    ///> Enables "delete single pad nets" option
+    ///< Enable "delete single pad nets" option.
     void SetDeleteSinglePadNets( bool aEnabled )
     {
         m_deleteSinglePadNets = aEnabled;
     }
 
-    ///> Enables warning option if a connectable pad is not found in netlist
+    ///< Enable warning option if a connectable pad is not found in netlist
-    ///> connectable = pad with a name and on a copper layer
+    ///< connectable = pad with a name and on a copper layer.
     void SetWarnPadNoNetInNetlist( bool aEnabled )
     {
         m_warnForNoNetPads = aEnabled;
     }
 
-    ///> Enables dry run mode (just report, no changes to PCB)
+    ///< Enable dry run mode (just report, no changes to PCB).
     void SetIsDryRun( bool aEnabled )
     {
         m_isDryRun = aEnabled;
     }
 
-    ///> Enables replacing footprints with new ones
+    ///< Enable replacing footprints with new ones.
     void SetReplaceFootprints( bool aEnabled )
     {
         m_replaceFootprints = aEnabled;
     }
 
-    ///> Enables removing unused components
+    ///< Enable removing unused components.
     void SetDeleteUnusedComponents( bool aEnabled )
     {
         m_deleteUnusedComponents = aEnabled;
     }
 
-    ///> Enables component lookup by timestamp instead of reference
+    ///< Enable component lookup by timestamp instead of reference.
     void SetLookupByTimestamp( bool aEnabled )
     {
         m_lookupByTimestamp = aEnabled;

pcbnew/pad.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -69,7 +69,8 @@ public:
 
     /*
      * Default layers used for pads, according to the pad type.
-     * this is default values only, they can be changed for a given pad
+     *
+     * This is default values only, they can be changed for a given pad.
      */
     static LSET PTHMask();          ///< layer set for a through hole pad
     static LSET SMDMask();          ///< layer set for a SMD pad on Front layer
@@ -109,22 +110,22 @@ public:
     bool IsLocked() const override;
 
     /**
-     * Imports the pad settings from aMasterPad.
+     * Import the pad settings from \a aMasterPad.
-     * The result is "this" has the same settinds (sizes, shapes ... )
+     *
-     * as aMasterPad
+     * The result is "this" has the same settings (sizes, shapes ... ) as \a aMasterPad.
-     * @param aMasterPad = the template pad
+     *
+     * @param aMasterPad the template pad.
      */
     void ImportSettingsFrom( const PAD& aMasterPad );
 
     /**
-     * @return true if the pad has a footprint parent flipped
+     * @return true if the pad has a footprint parent flipped on the back/bottom layer.
-     * (on the back/bottom layer)
      */
     bool IsFlipped() const;
 
     /**
-     * Set the pad name (sometimes called pad number, although
+     * Set the pad name (sometimes called pad number, although it can be an array reference
-     * it can be an array reference like AA12).
+     * like AA12).
      */
     void SetName( const wxString& aName ) { m_name = aName; }
     const wxString& GetName() const { return m_name; }
@@ -144,8 +145,6 @@ public:
     /**
      * Before we had custom pad shapes it was common to have multiple overlapping pads to
      * represent a more complex shape.
-     * @param other
-     * @return
      */
     bool SameLogicalPadAs( const PAD* other ) const
     {
@@ -176,14 +175,12 @@ public:
     wxPoint GetPosition() const override { return m_pos; }
 
     /**
-     * Function GetAnchorPadShape
      * @return the shape of the anchor pad shape, for custom shaped pads.
      */
     PAD_SHAPE_T GetAnchorPadShape() const       { return m_anchorPadShape; }
 
     /**
-     * @return the option for the custom pad shape to use as clearance area
+     * @return the option for the custom pad shape to use as clearance area in copper zones.
-     * in copper zones
      */
     CUST_PAD_SHAPE_IN_ZONE GetCustomShapeInZoneOpt() const
     {
@@ -191,8 +188,8 @@ public:
     }
 
     /**
-     * Set the option for the custom pad shape to use as clearance area
+     * Set the option for the custom pad shape to use as clearance area in copper zones.
-     * in copper zones
+     *
      * @param aOption is the clearance area shape CUST_PAD_SHAPE_IN_ZONE option
      */
     void SetCustomShapeInZoneOpt( CUST_PAD_SHAPE_IN_ZONE aOption )
@@ -201,10 +198,10 @@ public:
     }
 
     /**
-     * Function SetAnchorPadShape
+     * Set the shape of the anchor pad for custom shaped pads.
-     * Set the shape of the anchor pad for custm shped pads.
+     *
-     * @param the shape of the anchor pad shape( currently, only
+     * @param aShape is the shape of the anchor pad shape( currently, only #PAD_SHAPE_RECT or
-     * PAD_SHAPE_RECT or PAD_SHAPE_CIRCLE.
+     *               #PAD_SHAPE_CIRCLE.
      */
     void SetAnchorPadShape( PAD_SHAPE_T aShape )
     {
@@ -214,8 +211,6 @@ public:
 
     /**
      * @return true if the pad is on any copper layer, false otherwise.
-     * pads can be only on tech layers to build special pads.
-     * they are therefore not always on a copper layer
      */
     bool IsOnCopperLayer() const override
     {
@@ -257,12 +252,12 @@ public:
      * Has meaning only for custom shape pads.
      * add a free shape to the shape list.
      * the shape can be
-     *   a polygon (outline can have a thickness)
+     *  - a polygon (outline can have a thickness)
-     *   a thick segment
+     *  - a thick segment
-     *   a filled circle (thickness == 0) or ring
+     *  - a filled circle (thickness == 0) or ring
-     *   a filled rect (thickness == 0) or rectangular outline
+     *  - a filled rect (thickness == 0) or rectangular outline
-     *   a arc
+     *  - a arc
-     *   a bezier curve
+     *  - a bezier curve
      */
     void AddPrimitivePoly( const SHAPE_POLY_SET& aPoly, int aThickness, bool aFilled );
     void AddPrimitivePoly( const std::vector<wxPoint>& aPoly, int aThickness, bool aFilled );
@@ -279,13 +274,14 @@ public:
     bool GetBestAnchorPosition( VECTOR2I& aPos );
 
     /**
-     * Merge all basic shapes to a SHAPE_POLY_SET
+     * Merge all basic shapes to a #SHAPE_POLY_SET.
-     * Note: The results are relative to the pad position, orientation 0.
+     *
+     * @note The results are relative to the pad position, orientation 0.
      */
     void MergePrimitivesAsPolygon( SHAPE_POLY_SET* aMergedPolygon, PCB_LAYER_ID aLayer ) const;
 
     /**
-     * clear the basic shapes list
+     * Clear the basic shapes list.
      */
     void DeletePrimitivesList();
 
@@ -301,7 +297,7 @@ public:
 
     /**
      * Flip (mirror) the primitives left to right or top to bottom, around the anchor position
-     * in custom pads
+     * in custom pads.
      */
     void FlipPrimitives( bool aFlipLeftRight );
 
@@ -312,7 +308,7 @@ public:
     void ReplacePrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList );
 
     /**
-     * Import a custom shape primites list (composed of basic shapes) and add items to the
+     * Import a custom shape primitive list (composed of basic shapes) and add items to the
      * current list.  Copies the input, which is not altered.
      */
     void AppendPrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList );
@@ -323,10 +319,11 @@ public:
     void AddPrimitive( PCB_SHAPE* aPrimitive );
 
     /**
-     * Function SetOrientation
+     * Set the rotation angle of the pad.
-     * sets the rotation angle of the pad.
+     *
-     * @param aAngle in tenths of degrees.  If it is outside of 0 - 3600, then it will be
+     * If \a aAngle is outside of 0 - 3600, then it will be normalized.
-     * normalized before being saved.
+     *
+     * @param aAngle in tenths of degrees.
      */
     void SetOrientation( double aAngle );
 
@@ -336,8 +333,7 @@ public:
     void SetOrientationDegrees( double aOrientation ) { SetOrientation( aOrientation*10.0 ); }
 
     /**
-     * Function GetOrientation
+     * Return the rotation angle of the pad in a variety of units (the basic call returns
-     * returns the rotation angle of the pad in a variety of units (the basic call returns
      * tenths of degrees).
      */
     double GetOrientation() const { return m_orient; }
@@ -369,7 +365,10 @@ public:
 
     // We don't currently have an attribute for APERTURE, and adding one will change the file
     // format, so for now just infer a copper-less pad to be an APERTURE pad.
-    bool IsAperturePad() const                  { return ( m_layerMask & LSET::AllCuMask() ).none(); }
+    bool IsAperturePad() const
+    {
+        return ( m_layerMask & LSET::AllCuMask() ).none();
+    }
 
     void SetPadToDieLength( int aLength )       { m_lengthPadToDie = aLength; }
     int GetPadToDieLength() const               { return m_lengthPadToDie; }
@@ -388,13 +387,13 @@ public:
     void SetLocalSolderPasteMarginRatio( double aRatio ) { m_localSolderPasteMarginRatio = aRatio; }
 
     /**
-     * Function TransformShapeWithClearanceToPolygon
      * Convert the pad shape to a closed polygon. Circles and arcs are approximated by segments.
-     * @param aCornerBuffer = a buffer to store the polygon
+     *
-     * @param aClearanceValue = the clearance around the pad
+     * @param aCornerBuffer a buffer to store the polygon.
-     * @param aMaxError = maximum error from true when converting arcs
+     * @param aClearanceValue the clearance around the pad.
-     * @param aErrorLoc = should the approximation error be placed outside or inside the polygon?
+     * @param aMaxError maximum error from true when converting arcs.
-     * @param ignoreLineWidth = used for edge cuts where the line width is only for visualization
+     * @param aErrorLoc should the approximation error be placed outside or inside the polygon?
+     * @param ignoreLineWidth used for edge cuts where the line width is only for visualization.
      */
     void TransformShapeWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer,
                                                PCB_LAYER_ID aLayer, int aClearanceValue,
@@ -402,13 +401,13 @@ public:
                                                bool ignoreLineWidth = false ) const override;
 
     /**
-     * Function TransformHoleWithClearanceToPolygon
+     * Build the corner list of the polygonal drill shape in the board coordinate system.
-     * Build the Corner list of the polygonal drill shape in the board coordinate system.
+     *
-     * @param aCornerBuffer = a buffer to fill.
+     * @param aCornerBuffer a buffer to fill.
-     * @param aInflateValue = the clearance or margin value.
+     * @param aInflateValue the clearance or margin value.
-     * @param aError = maximum deviation of an arc from the polygon approximation
+     * @param aError maximum deviation of an arc from the polygon approximation.
      * @param aErrorLoc = should the approximation error be placed outside or inside the polygon?
-     * @return false if the pad has no hole, true otherwise
+     * @return false if the pad has no hole, true otherwise.
      */
     bool TransformHoleWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, int aInflateValue,
                                               int aError, ERROR_LOC aErrorLoc ) const;
@@ -419,54 +418,47 @@ public:
     const std::shared_ptr<SHAPE_POLY_SET>& GetEffectivePolygon() const;
 
     /**
-     * Function GetEffectiveHoleShape
+     * Return a SHAPE object representing the pad's hole.
-     * Returns a SHAPE object representing the pad's hole.
      */
     const SHAPE_SEGMENT* GetEffectiveHoleShape() const;
 
     /**
-     * Function GetBoundingRadius
+     * Return the radius of a minimum sized circle which fully encloses this pad.
-     * returns the radius of a minimum sized circle which fully encloses this pad.
+     *
      * The center is the pad position NOT THE SHAPE POS!
      */
     int GetBoundingRadius() const;
 
     /**
-     * Function GetLocalClearanceOverrides
+     * Return any local clearance overrides set in the "classic" (ie: pre-rule) system.
-     * returns any local clearance overrides set in the "classic" (ie: pre-rule) system.
+     *
-     * @param aSource [out] optionally reports the source as a user-readable string
+     * @param aSource [out] optionally reports the source as a user-readable string.
-     * @return int - the clearance in internal units.
+     * @return the clearance in internal units.
      */
     int GetLocalClearanceOverrides( wxString* aSource ) const override;
 
-   // Mask margins handling:
-
     /**
-     * Function GetSolderMaskMargin
      * @return the margin for the solder mask layer
-     * usually > 0 (mask shape bigger than pad)
+     *
-     * For pads also on copper layers, the value (used to build a default shape) is
+     * Usually > 0 (mask shape bigger than pad).  For pads **not** on copper layers, the value
-     * 1 - the local value
+     * is the local value because there is no default shape to build.  For pads also on copper
-     * 2 - if 0, the parent footprint value
+     * layers, the value (used to build a default shape) is:
-     * 3 - if 0, the global value
+     *  1 the local value
-     * For pads NOT on copper layers, the value is the local value because there is no default
+     *  2 if 0, the parent footprint value
-     * shape to build
+     *  3 if 0, the global value
      */
     int GetSolderMaskMargin() const;
 
     /**
-     * Function GetSolderPasteMargin
+     * Usually < 0 (mask shape smaller than pad)because the margin can be dependent on the pad
-     * @return the margin for the solder mask layer
+     * size, the margin has a x and a y value.  For pads **not** on copper layers, the value is
-     * usually < 0 (mask shape smaller than pad)
+     * the local value because there is no default shape to build.  For pads also on copper
-     * because the margin can be dependent on the pad size, the margin has a x and a y value
+     * layers, the value (used to build a default shape) is:
+     *  1 the local value
+     *  2 if 0, the parent footprint value
+     *  3 if 0, the global value
      *
-     * For pads also on copper layers, the value (used to build a default shape) is
+     * @return the margin for the solder mask layer.
-     * 1 - the local value
-     * 2 - if 0, the parent footprint value
-     * 3 - if 0, the global value
-     *
-     * For pads NOT on copper layers, the value is the local value because there is
-     * no default shape to build
     */
     wxSize GetSolderPasteMargin() const;
 
@@ -476,6 +468,7 @@ public:
     /**
      * Return the zone connection in effect (either locally overridden or overridden in the
      * parent footprint).
+     *
      * Optionally reports on the source of the property (pad, parent footprint or zone).
      */
     ZONE_CONNECTION GetEffectiveZoneConnection( wxString* aSource = nullptr ) const;
@@ -483,7 +476,6 @@ public:
     /**
      * Set the width of the thermal spokes connecting the pad to a zone.  If != 0 this will
      * override similar settings in the parent footprint and zone.
-     * @param aWidth
      */
     void SetThermalSpokeWidth( int aWidth ) { m_thermalWidth = aWidth; }
     int GetThermalSpokeWidth() const { return m_thermalWidth; }
@@ -502,8 +494,8 @@ public:
     int GetEffectiveThermalGap( wxString* aSource = nullptr ) const;
 
     /**
-     * Function SetRoundRectCornerRadius
+     * Has meaning only for rounded rectangle pads.
-     * has meaning only for rounded rect pads
+     *
      * @return The radius of the rounded corners for this pad.
      */
     void SetRoundRectCornerRadius( double aRadius );
@@ -512,7 +504,8 @@ public:
     wxPoint ShapePos() const;
 
     /**
-     * has meaning only for rounded rect pads
+     * Has meaning only for rounded rectangle pads.
+     *
      * Set the ratio between the smaller X or Y size and the rounded corner radius.
      * Cannot be > 0.5; the normalized IPC-7351C value is 0.25
      */
@@ -520,7 +513,8 @@ public:
     double GetRoundRectRadiusRatio() const { return m_roundedCornerScale; }
 
     /**
-     * has meaning only for chamfered rect pads
+     * Has meaning only for chamfered rectangular pads.
+     *
      * Set the ratio between the smaller X or Y size and chamfered corner size.
      * Cannot be < 0.5.
      */
@@ -528,30 +522,32 @@ public:
     double GetChamferRectRatio() const { return m_chamferScale; }
 
     /**
-     * has meaning only for chamfered rect pads
+     * Has meaning only for chamfered rectangular pads.
-     * set the position of the chamfers for orientation 0.
+     *
-     * @param aPositions a bit-set of RECT_CHAMFER_POSITIONS
+     * Set the position of the chamfers for orientation 0.
+     *
+     * @param aPositions a bit-set of #RECT_CHAMFER_POSITIONS.
      */
     void SetChamferPositions( int aPositions ) { m_chamferPositions = aPositions; }
     int GetChamferPositions() const { return m_chamferPositions; }
 
     /**
-     * Function GetSubRatsnest
+     * @return the netcode.
-     * @return int - the netcode
      */
     int GetSubRatsnest() const                  { return m_subRatsnest; }
     void SetSubRatsnest( int aSubRatsnest )     { m_subRatsnest = aSubRatsnest; }
 
     /**
-     * Sets the unconnected removal property.  If true, the copper is removed on zone fill
+     * Set the unconnected removal property.
-     * or when specifically requested when the pad is not connected on a layer.  This requires
+     *
-     * that there be a through hole.
+     * If true, the copper is removed on zone fill or when specifically requested when the pad
+     * is not connected on a layer.  This requires that there be a through hole.
      */
     void SetRemoveUnconnected( bool aSet )      { m_removeUnconnectedLayer = aSet; }
     bool GetRemoveUnconnected() const           { return m_removeUnconnectedLayer; }
 
     /**
-     * Sets whether we keep the top and bottom connections even if they are not connected
+     * Set whether we keep the top and bottom connections even if they are not connected.
      */
     void SetKeepTopBottom( bool aSet )      { m_keepTopBottomLayer = aSet; }
     bool GetKeepTopBottom() const           { return m_keepTopBottomLayer; }
@@ -564,7 +560,8 @@ public:
     }
 
     /**
-     * Checks to see whether the pad should be flashed on the specific layer
+     * Check to see whether the pad should be flashed on the specific layer.
+     *
      * @param aLayer Layer to check for connectivity
      * @param aIncludeZones We include zones in potentially connected elements when drawing
      * @return true if connected by pad or track (or optionally zone)
@@ -572,10 +569,12 @@ public:
     bool FlashLayer( int aLayer, bool aIncludeZones = false  ) const;
 
     /**
-     * Checks to see if the pad should be flashed to any of the layers in the set
+     * Check to see if the pad should be flashed to any of the layers in the set.
+     *
      * @param aLayers set of layers to check the via against
      * @param aIncludeZones We include zones in potentially connected elements when drawing
-     * @return true if connected by pad or track (or optionally zone) on any of the associated layers
+     * @return true if connected by pad or track (or optionally zone) on any of the associated
+     *         layers
      */
     bool FlashLayer( LSET aLayers, bool aIncludeZones = false  ) const;
 
@@ -588,22 +587,22 @@ public:
     }
 
     /**
-     * Function GetBoundingBox
      * The bounding box is cached, so this will be efficient most of the time.
      */
     const EDA_RECT GetBoundingBox() const override;
 
-    ///> Set absolute coordinates.
+    ///< Set absolute coordinates.
     void SetDrawCoord();
 
     //todo: Remove SetLocalCoord along with m_pos
-    ///> Set relative coordinates.
+    ///< Set relative coordinates.
     void SetLocalCoord();
 
     /**
-     * Function Compare
+     * Compare two pads and return 0 if they are equal.
-     * compares two pads and return 0 if they are equal.
+     *
-     * @return int - <0 if left less than right, 0 if equal, >0 if left greater than right.
+     * @return less than 0 if left less than right, 0 if equal, or greater than 0 if left
+     *         greater than right.
      */
     static int Compare( const PAD* padref, const PAD* padcmp );
 
@@ -621,13 +620,11 @@ public:
     BITMAP_DEF GetMenuImage() const override;
 
     /**
-     * Function ShowPadShape
+     * @return the GUI-appropriate name of the shape.
-     * @return the GUI-appropriate name of the shape
      */
     wxString ShowPadShape() const;
 
     /**
-     * Function ShowPadAttr
      * @return the GUI-appropriate description of the pad type (attribute) : Std, SMD ...
      */
     wxString ShowPadAttr() const;
@@ -635,7 +632,8 @@ public:
     EDA_ITEM* Clone() const override;
 
     /**
-     * same as Clone, but returns a PAD item.
+     * Same as Clone, but returns a PAD item.
+     *
      * Useful mainly for python scripts, because Clone returns an EDA_ITEM.
      */
     PAD* ClonePad() const
@@ -644,7 +642,7 @@ public:
     }
 
     /**
-     * Rebuilds the effective shape cache (and bounding box and radius) for the pad and clears
+     * Rebuild the effective shape cache (and bounding box and radius) for the pad and clears
      * the dirty bit.
      */
     void BuildEffectiveShapes( PCB_LAYER_ID aLayer ) const;
@@ -710,7 +708,7 @@ private:
 
     PAD_DRILL_SHAPE_T m_drillShape;         // PAD_DRILL_SHAPE_CIRCLE, PAD_DRILL_SHAPE_OBLONG
 
-    double            m_roundedCornerScale; // Scaling factor of min(width, hieght) to corner
+    double            m_roundedCornerScale; // Scaling factor of min(width, height) to corner
                                             //   radius, default 0.25
     double            m_chamferScale;       // Scaling factor of min(width, height) to chamfer
                                             //   size, default 0.25
@@ -746,11 +744,14 @@ private:
 
     int         m_lengthPadToDie;   // Length net from pad to die, inside the package
 
-    bool        m_removeUnconnectedLayer;  // If true, the pad copper is removed for layers that are not connected
+    ///< If true, the pad copper is removed for layers that are not connected.
-    bool        m_keepTopBottomLayer;      // When removing unconnected pads, keep the top and bottom pads
+    bool        m_removeUnconnectedLayer;
+
+    ///< When removing unconnected pads, keep the top and bottom pads.
+    bool        m_keepTopBottomLayer;
 
     /*
-     * Pad clearances, margins, etc. exist in a hiearchy.  If a given level is specified then
+     * Pad clearances, margins, etc. exist in a hierarchy.  If a given level is specified then
      * the remaining levels are NOT consulted.
      *
      * LEVEL 1: (highest priority) local overrides (pad, footprint, etc.)

pcbnew/pcb_base_edit_frame.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
- * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -54,96 +55,90 @@ public:
      * then creates a new footprint library at that location.
      * If library exists, user is warned about that, and is given a chance
      * to abort the new creation, and in that case existing library is first deleted.
-     * @param aProposedName is the inital path and filename shown in the file chooser dialog
      *
-     * @return wxString - the newly created library path if library was successfully
+     * @param aProposedName is the initial path and filename shown in the file chooser dialog.
-     *   created, else wxEmptyString because user aborted or error.
+     * @return The newly created library path if library was successfully created, else
+     *         wxEmptyString because user aborted or error.
      */
     wxString CreateNewLibrary( const wxString& aLibName = wxEmptyString,
                                const wxString& aProposedName = wxEmptyString );
 
     /**
-     * Function AddLibrary
      * Add an existing library to either the global or project library table.
+     *
      * @param aFileName the library to add; a file open dialog will be displayed if empty.
-     * @return true if successfully added
+     * @return true if successfully added.
      */
     bool AddLibrary(const wxString& aLibName = wxEmptyString);
 
     /**
-     * Function OnEditItemRequest
+     * Install the corresponding dialog editor for the given item.
-     * Install the corresponding dialog editor for the given item
+     *
-     * @param aDC = the current device context
+     * @param aDC the current device context.
-     * @param aItem = a pointer to the BOARD_ITEM to edit
+     * @param aItem a pointer to the BOARD_ITEM to edit.
      */
     virtual void OnEditItemRequest( BOARD_ITEM* aItem ) = 0;
 
-    // Undo buffer handling
-
     /**
-     * Function SaveCopyInUndoList
+     * Create a new entry in undo list of commands.
-     * Creates a new entry in undo list of commands.
+     *
-     * add a picker to handle aItemToCopy
+     * Add a picker to handle \a  aItemToCopy.
-     * @param aItemToCopy = the board item modified by the command to undo
+     *
-     * @param aTypeCommand = command type (see enum UNDO_REDO)
+     * @param aItemToCopy the board item modified by the command to undo.
-     * @param aTransformPoint = the reference point of the transformation, for
+     * @param aTypeCommand command type (see enum UNDO_REDO).
-     *                          commands like move
+     * @param aTransformPoint the reference point of the transformation, for commands like move
      */
     void SaveCopyInUndoList( EDA_ITEM* aItemToCopy, UNDO_REDO aTypeCommand,
                              const wxPoint& aTransformPoint = wxPoint( 0, 0 ) ) override;
 
     /**
-     * Function SaveCopyInUndoList
+     * Create a new entry in undo list of commands.
-     * Creates a new entry in undo list of commands.
+     *
-     * add a list of pickers to handle a list of items
+     * Add a list of pickers to handle a list of items.
-     * @param aItemsList = the list of items modified by the command to undo
+     *
-     * @param aTypeCommand = command type (see enum UNDO_REDO)
+     * @param aItemsList the list of items modified by the command to undo.
-     * @param aTransformPoint = the reference point of the transformation,
+     * @param aTypeCommand command type (see enum UNDO_REDO).
-     *                          for commands like move
+     * @param aTransformPoint the reference point of the transformation for commands like move.
      */
     void SaveCopyInUndoList( const PICKED_ITEMS_LIST& aItemsList, UNDO_REDO aTypeCommand,
                              const wxPoint& aTransformPoint = wxPoint( 0, 0 ) ) override;
 
     /**
-     * Function RestoreCopyFromRedoList
      * Redo the last edit:
      *  - Save the current board in Undo list
      *  - Get an old version of the board from Redo list
-     *  @return none
      */
     void RestoreCopyFromRedoList( wxCommandEvent& aEvent );
 
     /**
-     * Function RestoreCopyFromUndoList
      * Undo the last edit:
      *  - Save the current board in Redo list
      *  - Get an old version of the board from Undo list
-     *  @return none
      */
     void RestoreCopyFromUndoList( wxCommandEvent& aEvent );
 
     /**
-     * Performs an undo of the last edit WITHOUT logging a corresponding redo.  Used to cancel
+     * Perform an undo of the last edit **without** logging a corresponding redo.  Used to cancel
      * an in-progress operation.
      */
     void RollbackFromUndo();
 
     /**
-     * Function PutDataInPreviousState
      * Used in undo or redo command.
-     * Put data pointed by List in the previous state, i.e. the state memorized by List
+     *
-     * @param aList = a PICKED_ITEMS_LIST pointer to the list of items to undo/redo
+     * Put data pointed by List in the previous state, i.e. the state memorized by \a aList.
-     * @param aRedoCommand = a bool: true for redo, false for undo
+     *
-     * @param aRebuildRatsnet = a bool: true to rebuild ratsnest (normal use), false to just
+     * @param aList a PICKED_ITEMS_LIST pointer to the list of items to undo/redo.
-     * retrieve last state (used in abort commands that do not need to rebuild ratsnest)
+     * @param aRedoCommand true for redo, false for undo.
+     * @param aRebuildRatsnet a bool: true to rebuild ratsnest (normal use), false to just
+     *                        retrieve last state (used in abort commands that do not need
+     *                        to rebuild ratsnest).
      */
-    void PutDataInPreviousState( PICKED_ITEMS_LIST* aList,
+    void PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRedoCommand,
-                                 bool               aRedoCommand,
                                  bool aRebuildRatsnet = true );
 
     /**
-     * Function UndoRedoBlocked
+     * Check if the undo and redo operations are currently blocked.
-     * Checks if the undo and redo operations are currently blocked.
      */
     bool UndoRedoBlocked() const
     {
@@ -151,8 +146,7 @@ public:
     }
 
     /**
-     * Function UndoRedoBlock
+     * Enable/disable undo and redo operations.
-     * Enables/disable undo and redo operations.
      */
     void UndoRedoBlock( bool aBlock = true )
     {
@@ -160,35 +154,31 @@ public:
     }
 
     /**
-     * Function SetGridVisibility()
-     *
      * Override this function in the PCB_BASE_EDIT_FRAME to refill the layer widget
      *
-     * @param aVisible = true if the grid must be shown
+     * @param aVisible true if the grid must be shown.
      */
     void SetGridVisibility( bool aVisible ) override;
 
     void SetObjectVisible( GAL_LAYER_ID aLayer, bool aVisible = true );
 
     /**
-     * Function GetRotationAngle()
+     * Return the angle used for rotate operations.
-     * Returns the angle used for rotate operations.
      */
     int GetRotationAngle() const { return m_rotationAngle; }
 
     /**
-     * Function SetRotationAngle()
+     * Set the angle used for rotate operations.
-     * Sets the angle used for rotate operations.
      */
     void SetRotationAngle( int aRotationAngle );
 
     void ShowTextPropertiesDialog( BOARD_ITEM* aText );
     void ShowGraphicItemPropertiesDialog( BOARD_ITEM* aItem );
 
-    ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas()
+    ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas()
     void ActivateGalCanvas() override;
 
-    ///> @copydoc PCB_BASE_FRAME::SetBoard()
+    ///< @copydoc PCB_BASE_FRAME::SetBoard()
     virtual void SetBoard( BOARD* aBoard ) override;
 
     COLOR_SETTINGS* GetColorSettings() const override;
@@ -200,23 +190,23 @@ public:
     // use EDA_BASE_FRAME::PushCommandToRedoList( PICKED_ITEMS_LIST* aItem )
 
     /**
-     * Function ClearUndoORRedoList
+     * Free the undo or redo list from List element.
-     * free the undo or redo list from List element
+     *
-     *  Wrappers are deleted.
+     * Wrappers are deleted.  Data pointed by wrappers are deleted if not in use in schematic
-     *  datas pointed by wrappers are deleted if not in use in schematic
+     * i.e. when they are copy of a schematic item or they are no more in use (DELETED).
-     *  i.e. when they are copy of a schematic item or they are no more in use
+     * Items are removed from the beginning of the list so this function can be called to
-     *  (DELETED)
+     * remove old commands.
-     * @param whichList = the UNDO_REDO_CONTAINER to clear
+     *
-     * @param aItemCount = the count of items to remove. < 0 for all items
+     * @param whichList the #UNDO_REDO_CONTAINER to clear.
-     * items are removed from the beginning of the list.
+     * @param aItemCount the count of items to remove. < 0 for all items.
-     * So this function can be called to remove old commands
      */
     void ClearUndoORRedoList( UNDO_REDO_LIST whichList, int aItemCount = -1 ) override;
 
     /**
-     * Returns the absolute path to the design rules file for the currently-loaded board.
+     * Return the absolute path to the design rules file for the currently-loaded board.
-     * Note that there is no guarantee that this file actually exists and can be opened!
+     *
-     * NOTE: only really makes sense from PcbNew, but is needed in PCB_BASE_EDIT_FRAME::SetBoard
+     * @note There is no guarantee that this file actually exists and can be opened!  It only
+     *       makes sense from PcbNew but is needed in #PCB_BASE_EDIT_FRAME::SetBoard.
      */
     wxString GetDesignRulesPath();
 

pcbnew/pcb_draw_panel_gal.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -45,17 +47,17 @@ public:
     virtual ~PCB_DRAW_PANEL_GAL();
 
     /**
-     * Function DisplayBoard
+     * Add all items from the current board to the VIEW, so they can be displayed by GAL.
-     * adds all items from the current board to the VIEW, so they can be displayed by GAL.
+     *
      * @param aBoard is the PCB to be loaded.
      */
     void DisplayBoard( BOARD* aBoard );
 
     /**
-     * Function SetWorksheet
+     * Set (or updates) worksheet used by the draw panel.
-     * Sets (or updates) worksheet used by the draw panel.
+     *
-     * @param aWorksheet is the worksheet to be used.
+     * @param aWorksheet is the worksheet to be used.  The object is then owned by
-     *        The object is then owned by PCB_DRAW_PANEL_GAL.
+     *                   #PCB_DRAW_PANEL_GAL.
      */
     void SetWorksheet( KIGFX::WS_PROXY_VIEW_ITEM* aWorksheet );
 
@@ -63,63 +65,62 @@ public:
 
     // TODO(JE) Look at optimizing this out
     /**
-     * Updates the color settings in the painter and GAL
+     * Update the color settings in the painter and GAL.
      */
     void UpdateColors();
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::SetHighContrastLayer()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::SetHighContrastLayer()
     virtual void SetHighContrastLayer( int aLayer ) override
     {
         SetHighContrastLayer( static_cast< PCB_LAYER_ID >( aLayer ) );
     }
 
-    ///> SetHighContrastLayer(), with some extra smarts for PCB
+    ///< SetHighContrastLayer(), with some extra smarts for PCB.
     void SetHighContrastLayer( PCB_LAYER_ID aLayer );
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer()
     virtual void SetTopLayer( int aLayer ) override
     {
         SetTopLayer( static_cast< PCB_LAYER_ID >( aLayer ) );
     }
 
-    ///> SetTopLayer(), with some extra smarts for PCB
+    ///< SetTopLayer(), with some extra smarts for PCB.
     void SetTopLayer( PCB_LAYER_ID aLayer );
 
     /**
-     * Function SyncLayersVisibility
+     * Update "visibility" property of each layer of a given #BOARD.
-     * Updates "visibility" property of each layer of a given BOARD.
+     *
      * @param aBoard contains layers visibility settings to be applied.
      */
     void SyncLayersVisibility( const BOARD* aBoard );
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo()
     void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::OnShow()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::OnShow()
     void OnShow() override;
 
     bool SwitchBackend( GAL_TYPE aGalType ) override;
 
-    ///> Forces refresh of the ratsnest visual representation
+    ///< Force refresh of the ratsnest visual representation.
     void RedrawRatsnest();
 
-    ///> @copydoc EDA_DRAW_PANEL_GAL::GetDefaultViewBBox()
+    ///< @copydoc EDA_DRAW_PANEL_GAL::GetDefaultViewBBox()
     BOX2I GetDefaultViewBBox() const override;
 
     virtual KIGFX::PCB_VIEW* GetView() const override;
 
 protected:
-
+    ///< Reassign layer order to the initial settings.
-    ///> Reassigns layer order to the initial settings.
     void setDefaultLayerOrder();
 
-    ///> Sets rendering targets & dependencies for layers.
+    ///< Set rendering targets & dependencies for layers.
     void setDefaultLayerDeps();
 
-    ///> Currently used worksheet
+    ///< Currently used worksheet.
     std::unique_ptr<KIGFX::WS_PROXY_VIEW_ITEM> m_worksheet;
 
-    ///> Ratsnest view item
+    ///< Ratsnest view item
     std::unique_ptr<KIGFX::RATSNEST_VIEWITEM> m_ratsnest;
 };
 

pcbnew/pcb_edit_frame.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2010 Jean-Pierre Charras, jp.charras@wanadoo.fr
- * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2010-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -64,8 +64,7 @@ enum LAST_PATH_TYPE : unsigned int;
 namespace PCB { struct IFACE; }     // KIFACE_I is in pcbnew.cpp
 
 /**
- * PCB_EDIT_FRAME
+ * The main frame for Pcbnew.
- * is the main frame for Pcbnew.
  *
  * See also class PCB_BASE_FRAME(): Basic class for Pcbnew and GerbView.
  */
@@ -99,53 +98,52 @@ protected:
 
     LAYER_TOOLBAR_ICON_VALUES m_prevIconVal;
 
-    // The Tool Framework initalization
+    // The Tool Framework initialization
     void setupTools();
     void setupUIConditions() override;
 
     /**
-     * switches currently used canvas (Cairo / OpenGL).
+     * Switch currently used canvas (Cairo / OpenGL).
+     *
      * It also reinit the layers manager that slightly changes with canvases
      */
     void SwitchCanvas( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ) override;
 
 #if defined(KICAD_SCRIPTING) && defined(KICAD_SCRIPTING_ACTION_MENU)
     /**
-     * Function buildActionPluginMenus
      * Fill action menu with all registered action plugins
      */
     void buildActionPluginMenus( ACTION_MENU* aActionMenu );
 
     /**
-     * Function AddActionPluginTools
      * Append action plugin buttons to main toolbar
      */
     void AddActionPluginTools();
 
 	/**
-	 * Function RunActionPlugin
+	 * Execute action plugin's Run() method and updates undo buffer.
-	 * Executes action plugin's Run() method and updates undo buffer
+     *
 	 * @param aActionPlugin action plugin
 	 */
 	void RunActionPlugin( ACTION_PLUGIN* aActionPlugin );
 
     /**
-     * Function OnActionPluginMenu
+     * Launched by the menu when an action is called.
-     * Launched by the menu when an action is called
+     *
      * @param aEvent sent by wx
      */
     void OnActionPluginMenu( wxCommandEvent& aEvent);
 
     /**
-     * Function OnActionPluginButton
+     * Launched by the button when an action is called.
-     * Launched by the button when an action is called
+     *
      * @param aEvent sent by wx
      */
     void OnActionPluginButton( wxCommandEvent& aEvent );
 
     /**
-     * Function OnActionPluginRefresh
+     * Refresh plugin list (reload Python plugins).
-     * Refresh plugin list (reload Python plugins)
+     *
      * @param aEvent sent by wx
      */
     void OnActionPluginRefresh( wxCommandEvent& aEvent)
@@ -154,8 +152,8 @@ protected:
     }
 
     /**
-     * Function OnActionPluginRefresh
+     * Refresh plugin list (reload Python plugins).
-     * Refresh plugin list (reload Python plugins)
+     *
      * @param aEvent sent by wx
      */
     void OnActionPluginShowFolder( wxCommandEvent& aEvent)
@@ -164,9 +162,10 @@ protected:
     }
 #endif
 
-    /** Has meaning only if KICAD_SCRIPTING_WXPYTHON option is
+    /**
-     * not defined
+     * Has meaning only if KICAD_SCRIPTING_WXPYTHON option is not defined.
-     * @return the frame name identifier for the python console frame
+     *
+     * @return the frame name identifier for the python console frame.
      */
     static const wxChar * pythonConsoleNameId()
     {
@@ -182,13 +181,12 @@ protected:
     }
 
     /**
-     * Updates the state of the GUI after a new board is loaded or created
+     * Update the state of the GUI after a new board is loaded or created.
      */
     void onBoardLoaded();
 
     /**
-     * Function doAutoSave
+     * Perform auto save when the board has been modified and not saved within the
-     * performs auto save when the board has been modified and not saved within the
      * auto save interval.
      *
      * @return true if the auto save was successful.
@@ -196,13 +194,13 @@ protected:
     bool doAutoSave() override;
 
     /**
-     * Function isautoSaveRequired
+     * Return true if the board has been modified.
-     * returns true if the board has been modified.
      */
     bool isAutoSaveRequired() const override;
 
     /**
      * Load the given filename but sets the path to the current project path.
+     *
      * @param full file path of file to be imported.
      * @param aFileType PCB_FILE_T value for file type
      */
@@ -220,6 +218,7 @@ protected:
 
 public:
     PCB_LAYER_BOX_SELECTOR* m_SelLayerBox;  // a combo box to display and select active layer
+
     wxChoice* m_SelTrackWidthBox;        // a choice box to display and select current track width
     wxChoice* m_SelViaSizeBox;           // a choice box to display and select current via diameter
 
@@ -230,8 +229,7 @@ public:
     virtual ~PCB_EDIT_FRAME();
 
     /**
-     * Function loadFootprints
+     * Load the footprints for each #SCH_COMPONENT in \a aNetlist from the list of libraries.
-     * loads the footprints for each #COMPONENT in \a aNetlist from the list of libraries.
      *
      * @param aNetlist is the netlist of components to load the footprints into.
      * @param aReporter is the #REPORTER object to report to.
@@ -281,24 +279,24 @@ public:
     void UpdateUserInterface();
 
     /**
-     * Execute a remote command send by Eeschema via a socket,
+     * Execute a remote command send by Eeschema via a socket, port KICAD_PCB_PORT_SERVICE_NUMBER
-     * port KICAD_PCB_PORT_SERVICE_NUMBER (currently 4242)
+     * (currently 4242).
-     * this is a virtual function called by EDA_DRAW_FRAME::OnSockRequest().
+     *
-     * @param cmdline = received command from socket
+     * This is a virtual function called by EDA_DRAW_FRAME::OnSockRequest().
+     *
+     * @param cmdline is the received command from socket.
      */
     void ExecuteRemoteCommand( const char* cmdline ) override;
 
     void KiwayMailIn( KIWAY_EXPRESS& aEvent ) override;
 
     /**
-     * Function ToPlotter
      * Open a dialog frame to create plot and drill files relative to the current board.
      */
     void ToPlotter( int aID );
 
     /**
-     * Function SVG_Print
+     * Show the Export to SVG file dialog.
-     * Shows the Export to SVG file dialog.
      */
     void ExportSVG( wxCommandEvent& event );
 
@@ -315,14 +313,12 @@ public:
     void UpdateViaSizeSelectBox( wxChoice* aViaSizeSelectBox, bool aEdit = true );
 
     /**
-     * Function GetGridColor() , virtual
      * @return the color of the grid
      */
     COLOR4D GetGridColor() override;
 
     /**
-     * Function SetGridColor() , virtual
+     * @param aColor the new color of the grid.
-     * @param aColor = the new color of the grid
      */
     void SetGridColor( COLOR4D aColor ) override;
 
@@ -332,23 +328,21 @@ public:
 #if defined(KICAD_SCRIPTING) && defined(KICAD_SCRIPTING_ACTION_MENU)
 
     /**
-     * Function GetActionPluginButtonVisible
+     * Return true if button visibility action plugin setting was set to true
-     * Returns true if button visibility action plugin setting was set to true
      * or it is unset and plugin defaults to true.
      */
     bool GetActionPluginButtonVisible( const wxString& aPluginPath, bool aPluginDefault );
 
     /**
-     * Function GetOrderedActionPlugins
+     * Return ordered list of plugins in sequence in which they should appear on toolbar or
-     * Returns ordered list of plugins in sequence in which they should appear on toolbar or in settings
+     * in settings
      */
     std::vector<ACTION_PLUGIN*> GetOrderedActionPlugins();
 
 #endif
 
     /**
-     * Function SaveProjectSettings
+     * Save changes to the project settings to the project (.pro) file.
-     * saves changes to the project settings to the project (.pro) file.
      */
     void SaveProjectSettings() override;
 
@@ -366,14 +360,15 @@ public:
 
     /**
      * Get the last path for a particular type.
-     * @return - Absolute path and file name of the last file successfully read.
+     *
+     * @return the absolute path and file name of the last file successfully read.
      */
     wxString GetLastPath( LAST_PATH_TYPE aType );
 
     /**
      * Set the path of the last file successfully read.
      *
-     * Note: the file path is converted to a path relative to the project file path.  If
+     * @note the file path is converted to a path relative to the project file path.  If
      *       the path cannot be made relative, than m_lastNetListRead is set to and empty
      *       string.  This could happen when the net list file is on a different drive than
      *       the project file.  The advantage of relative paths is that is more likely to
@@ -403,29 +398,26 @@ public:
     void ReCreateMenuBar() override;
 
     /**
-     * Re create the layer Box by clearing the old list, and building
+     * Recreate the layer box by clearing the old list and building a new one from the new
-     * le new one, from the new layers names and cole layers
+     * layer names and colors.
-     * @param aForceResizeToolbar = true to resize the parent toolbar
+     *
-     * false if not needed (mainly in parent toolbar creation,
+     * @param aForceResizeToolbar true to resize the parent toolbar false if not needed (mainly
-     * or when the layers names are not modified)
+     *                            in parent toolbar creation, or when the layers names are not
+     *                            modified)
      */
     void ReCreateLayerBox( bool aForceResizeToolbar = true );
 
 
     /**
-     * Function OnModify
+     * Must be called after a board change to set the modified flag.
-     * must be called after a board change to set the modified flag.
+     *
-     * <p>
+     * Reload the 3D view if required and calls the base PCB_BASE_FRAME::OnModify function
-     * Reloads the 3D view if required and calls the base PCB_BASE_FRAME::OnModify function
      * to update auxiliary information.
-     * </p>
      */
     void OnModify() override;
 
     /**
-     * Function SetActiveLayer
+     * Change the currently active layer to \a aLayer and also update the #APPEARANCE_CONTROLS.
-     * will change the currently active layer to \a aLayer and also
-     * update the APPEARANCE_CONTROLS.
      */
     void SetActiveLayer( PCB_LAYER_ID aLayer ) override;
 
@@ -439,9 +431,8 @@ public:
     void OnDisplayOptionsChanged() override;
 
     /**
-     * Function IsElementVisible
+     * Test whether a given element category is visible. Keep this as an inline function.
-     * tests whether a given element category is visible. Keep this as an
+     *
-     * inline function.
      * @param aElement is from the enum by the same name
      * @return bool - true if the element is visible.
      * @see enum GAL_LAYER_ID
@@ -449,58 +440,50 @@ public:
     bool IsElementVisible( GAL_LAYER_ID aElement ) const;
 
     /**
-     * Function SetElementVisibility
+     * Change the visibility of an element category.
-     * changes the visibility of an element category
+     *
-     * @param aElement is from the enum by the same name
+     * @param aElement is from the enum by the same name.
-     * @param aNewState The new visibility state of the element category
+     * @param aNewState The new visibility state of the element category.
-     * @see enum PCB_LAYER_ID
+     * @see enum PCB_LAYER_ID.
      */
     void SetElementVisibility( GAL_LAYER_ID aElement, bool aNewState );
 
-    ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas()
+    ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas()
     void ActivateGalCanvas() override;
 
-    /**
-     * Function ShowBoardSetupDialog
-     */
     void ShowBoardSetupDialog( const wxString& aInitialPage = wxEmptyString );
 
-    /* toolbars update UI functions: */
-
     void PrepareLayerIndicator( bool aForceRebuild = false );
 
     void ToggleLayersManager();
 
     /**
-     * Function DoGenFootprintsPositionFile
+     * Create an ASCII footprint position file.
-     * Creates an ascii footprint position file
+     *
-     * @param aFullFileName = the full file name of the file to create
+     * @param aFullFileName the full file name of the file to create.
-     * @param aUnitsMM = false to use inches, true to use mm in coordinates
+     * @param aUnitsMM false to use inches, true to use mm in coordinates.
-     * @param aForceSmdItems = true to force all footprints with smd pads in list
+     * @param aForceSmdItems true to force all footprints with smd pads in list,
-     *                       = false to put only footprints with option "INSERT" in list
+     *                       false to put only footprints with option "INSERT" in list
-     * @param aTopSide true to list footprints on front (top) side,
+     * @param aTopSide true to list footprints on front (top) side.
-     * @param aBottomSide true to list footprints on back (bottom) side,
+     * @param aBottomSide true to list footprints on back (bottom) side, if \a aTopSide and
-     * if aTopSide and aTopSide are true, list footprints on both sides
+     *                    \a aTopSide are true, list footprints on both sides.
-     * @param aFormatCSV = true to use a comma separated file (CSV) format; defautl = false
+     * @param aFormatCSV true to use a comma separated file (CSV) format; default = false
-     * @return the number of footprints found on aSide side,
+     * @return the number of footprints found on aSide side or -1 if the file could not be created.
-     *    or -1 if the file could not be created
      */
     int DoGenFootprintsPositionFile( const wxString& aFullFileName, bool aUnitsMM,
-                                     bool aForceSmdItems, bool aTopSide, bool aBottomSide, bool aFormatCSV = false );
+                                     bool aForceSmdItems, bool aTopSide, bool aBottomSide,
+                                     bool aFormatCSV = false );
 
     /**
-     * Function GenFootprintsReport
+     * Call #DoGenFootprintsReport to create a footprint report file
-     * Calls DoGenFootprintsReport to create a footprint reprot file
-     * See DoGenFootprintsReport for file format
      */
     void GenFootprintsReport( wxCommandEvent& event );
 
     /**
-     * Function DoGenFootprintsReport
+     * Create an ASCII footprint report file giving some infos on footprints and board outlines.
-     * Creates an ascii footprint report file giving some infos on footprints
+     *
-     * and board outlines
+     * @param aFullFilename the full file name of the file to create
-     * @param aFullFilename = the full file name of the file to create
+     * @param aUnitsMM false to use inches, true to use mm in coordinates
-     * @param aUnitsMM = false to use inches, true to use mm in coordinates
      * @return true if OK, false if error
      */
     bool DoGenFootprintsReport( const wxString& aFullFilename, bool aUnitsMM );
@@ -511,51 +494,49 @@ public:
     void OnClearFileHistory( wxCommandEvent& aEvent );
 
     /**
-     * Function Files_io
+     * Call #Files_io_from_id with the wxCommandEvent id.
+     *
      * @param event is the command event handler.
-     * do nothing else than call Files_io_from_id with the
-     * wxCommandEvent id
      */
     void Files_io( wxCommandEvent& event );
 
     /**
-     * Function Files_io_from_id
+     * Read and write board files according to \a aId.
-     * Read and write board files
+     *
-     * @param aId is an event ID ciming from file command events:
+     * Valid event IDs are:
-     * ID_LOAD_FILE
+     *  - ID_LOAD_FILE
-     * ID_MENU_RECOVER_BOARD_AUTOSAVE
+     *  - ID_MENU_RECOVER_BOARD_AUTOSAVE
-     * ID_NEW_BOARD
+     *  - ID_NEW_BOARD
-     * ID_SAVE_BOARD
+     *  - ID_SAVE_BOARD
-     * ID_COPY_BOARD_AS
+     *  - ID_COPY_BOARD_AS
-     * ID_SAVE_BOARD_AS
+     *  - ID_SAVE_BOARD_AS
-     * Files_io_from_id prepare parameters and calls the specialized function
+     *
+     * @param aId is an event ID coming from file command events:
      */
     bool Files_io_from_id( int aId );
 
     /**
-     * Function OpenProjectFiles    (was LoadOnePcbFile)
+     * Load a KiCad board (.kicad_pcb) from \a aFileName.
-     * loads a KiCad board (.kicad_pcb) from \a aFileName.
      *
-     * @param aFileSet - hold the BOARD file to load, a vector of one element.
+     * @param aFileSet hold the BOARD file to load, a vector of one element.
-     *
+     * @param aCtl KICTL_ bits, one to indicate that an append of the board file
-     * @param aCtl      - KICTL_ bits, one to indicate that an append of the board file
+     *             \a aFileName to the currently loaded file is desired.
-     *                      aFileName to the currently loaded file is desired.
      *             @see #KIWAY_PLAYER for bit defines.
      *
-     * @return bool - false if file load fails, otherwise true.
+     * @return false if file load fails, otherwise true.
     bool LoadOnePcbFile( const wxString& aFileName, bool aAppend = false,
                          bool aForceFileDialog = false );
      */
     bool OpenProjectFiles( const std::vector<wxString>& aFileSet, int aCtl = 0 ) override;
 
     /**
-     * Function SavePcbFile
+     * Writes the board data structures to \a a aFileName.
-     * writes the board data structures to \a a aFileName
+     *
-     * Creates backup when requested and update flags (modified and saved flgs)
+     * Create a backup when requested and update flags (modified and saved flags).
      *
      * @param aFileName The file name to write or wxEmptyString to prompt user for
      *                  file name.
-     * @param addToHistory controsl whether or not to add the saved file to the recent file list
+     * @param addToHistory controls whether or not to add the saved file to the recent file list
      * @param aChangeProject is true if the project should be changed to the new board filename
      * @return True if file was saved successfully.
      */
@@ -563,83 +544,72 @@ public:
                       bool aChangeProject = true );
 
     /**
-     * Function SavePcbCopy
+     * Write the board data structures to \a aFileName.
-     * writes the board data structures to \a a aFileName
-     * but unlike SavePcbFile, does not make anything else
-     * (no backup, borad fliename change, no flag changes ...)
-     * Used under a project mgr to save under a new name the current board
      *
+     * Unlike SavePcbFile, does not make anything else (no backup, broad filename change, no
+     * flag changes ...).  Used under a project mgr to save under a new name the current board.
      * When not under a project mgr, the full SavePcbFile is used.
+     *
      * @param aFileName The file name to write.
      * @param aCreateProject will create an empty project alongside the board file
      * @return True if file was saved successfully.
      */
     bool SavePcbCopy( const wxString& aFileName, bool aCreateProject = false );
 
-    // BOARD handling
-
     /**
-     * Function Clear_Pcb
+     * Delete all and reinitialize the current board.
-     * delete all and reinitialize the current board
+     *
-     * @param aQuery = true to prompt user for confirmation, false to initialize silently
+     * @param aQuery true to prompt user for confirmation, false to initialize silently.
-     * @param aFinal = if true, we are clearing the board to exit, so don't run more events
+     * @param aFinal if true, we are clearing the board to exit, so don't run more events.
      */
     bool Clear_Pcb( bool aQuery, bool aFinal = false );
 
-    ///> @copydoc PCB_BASE_FRAME::SetBoard()
+    ///< @copydoc PCB_BASE_FRAME::SetBoard()
     void SetBoard( BOARD* aBoard ) override;
 
-    ///> @copydoc PCB_BASE_FRAME::GetModel()
+    ///< @copydoc PCB_BASE_FRAME::GetModel()
     BOARD_ITEM_CONTAINER* GetModel() const override;
 
-    ///> @copydoc PCB_BASE_FRAME::SetPageSettings()
+    ///< @copydoc PCB_BASE_FRAME::SetPageSettings()
     void SetPageSettings( const PAGE_INFO& aPageSettings ) override;
 
     /**
-     * Function RecreateBOMFileFromBoard
+     * Recreates a .cmp file from the current loaded board.
-     * Recreates a .cmp file from the current loaded board
+     *
-     * this is the same as created by CvPcb.
+     * This is the same as created by CvPcb and can be used if this file is lost.
-     * can be used if this file is lost
      */
     void RecreateCmpFileFromBoard( wxCommandEvent& aEvent );
 
     /**
-     * Function ExportFootprintsToLibrary
      * Save footprints in a library:
-     * @param aStoreInNewLib:
-     *              true : save footprints in a existing lib. Existing footprints will be kept
-     *              or updated.
-     *              This lib should be in fp lib table, and is type is .pretty
-     *              false: save footprints in a new lib. It it is an existing lib,
-     *              previous footprints will be removed
      *
-     * @param aLibName:
+     * @param aStoreInNewLib true to save footprints in a existing library. Existing footprints
-     *              optional library name to create, stops dialog call.
+     *                       will be kept or updated.  This library should be in fp lib table,
-     *              must be called with aStoreInNewLib as true
+     *                       and is type is .pretty. False to save footprints in a new library.
+     *                       If it is an existing lib, previous footprints will be removed.
+     *
+     * @param aLibName optional library name to create, stops dialog call. Must be called with
+     *                 \a aStoreInNewLib as true.
      */
     void ExportFootprintsToLibrary( bool aStoreInNewLib, const wxString& aLibName = wxEmptyString,
                                     wxString* aLibPath = NULL );
 
     /**
-     * Function RecreateBOMFileFromBoard
+     * Create a BOM file from the current loaded board.
-     * Creates a BOM file from the current loaded board
      */
     void RecreateBOMFileFromBoard( wxCommandEvent& aEvent );
 
     /**
-     * Function ExportToGenCAD
+     * Create a file in  GenCAD 1.4 format from the current board.
-     * creates a file in  GenCAD 1.4 format from the current board.
      */
     void ExportToGenCAD( wxCommandEvent& event );
 
     /**
-     * Function OnExportVRML
+     * Export the current BOARD to a VRML file.
-     * will export the current BOARD to a VRML file.
      */
     void OnExportVRML( wxCommandEvent& event );
 
     /**
-     * Function ExportVRML_File
      * Creates the file(s) exporting current BOARD to a VRML file.
      *
      * @note When copying 3D shapes files, the new filename is build from the full path
@@ -652,19 +622,18 @@ public:
      * @note For 3D models built by a 3D modeler, the unit is 0,1 inches.  A specific scale
      *       is applied to 3D models to convert them to internal units.
      *
-     * @param aFullFileName = the full filename of the file to create
+     * @param aFullFileName the full filename of the file to create
-     * @param aMMtoWRMLunit = the VRML scaling factor:
+     * @param aMMtoWRMLunit the VRML scaling factor: 1.0 to export in mm. 0.001 for meters
-     *      1.0 to export in mm. 0.001 for meters
+     * @param aExport3DFiles true to copy 3D shapes in the subir a3D_Subdir
-     * @param aExport3DFiles = true to copy 3D shapes in the subir a3D_Subdir
      * @param aUseRelativePaths set to true to use relative paths instead of absolute paths
      *                          in the board VRML file URLs.
-     * @param aUsePlainPCB set to true to export a board with no copper or silkskreen;
+     * @param aUsePlainPCB set to true to export a board with no copper or silkscreen;
      *                          this is useful for generating a VRML file which can be
      *                          converted to a STEP model.
-     * @param a3D_Subdir = sub directory where 3D shapes files are copied.  This is only used
+     * @param a3D_Subdir sub directory where 3D shapes files are copied.  This is only used
-     *                     when aExport3DFiles == true
+     *                   when aExport3DFiles == true.
-     * @param aXRef = X value of PCB (0,0) reference point
+     * @param aXRef X value of PCB (0,0) reference point.
-     * @param aYRef = Y value of PCB (0,0) reference point
+     * @param aYRef Y value of PCB (0,0) reference point.
      * @return true if Ok.
      */
     bool ExportVRML_File( const wxString& aFullFileName, double aMMtoWRMLunit,
@@ -672,52 +641,47 @@ public:
                           const wxString& a3D_Subdir, double aXRef, double aYRef );
 
     /**
-     * Function OnExportIDF3
+     * Will export the current BOARD to a IDFv3 board and lib files.
-     * will export the current BOARD to a IDFv3 board and lib files.
      */
     void OnExportIDF3( wxCommandEvent& event );
 
     /**
-     * Function OnExportHyperlynx
+     * Will export the current BOARD to a Hyperlynx HYP file.
-     * will export the current BOARD to a Hyperlynx HYP file.
      */
     void OnExportHyperlynx( wxCommandEvent& event );
 
     /**
-     * Function Export_IDF3
      * Creates an IDF3 compliant BOARD (*.emn) and LIBRARY (*.emp) file.
      *
-     * @param aPcb = a pointer to the board to be exported to IDF
+     * @param aPcb a pointer to the board to be exported to IDF.
-     * @param aFullFileName = the full filename of the export file
+     * @param aFullFileName the full filename of the export file.
-     * @param aUseThou = set to true if the desired IDF unit is thou (mil)
+     * @param aUseThou set to true if the desired IDF unit is thou (mil).
-     * @param aXRef = the board Reference Point in mm, X value
+     * @param aXRef the board Reference Point in mm, X value.
-     * @param aYRef = the board Reference Point in mm, Y value
+     * @param aYRef the board Reference Point in mm, Y value.
-     * @return true if OK
+     * @return true if OK.
      */
     bool Export_IDF3( BOARD* aPcb, const wxString& aFullFileName,
                       bool aUseThou, double aXRef, double aYRef );
 
     /**
-     * Function OnExportSTEP
+     * Export the current BOARD to a STEP assembly.
-     * Exports the current BOARD to a STEP assembly.
      */
     void OnExportSTEP( wxCommandEvent& event );
 
     /**
-     * Function ExportSpecctraFile
+     * Export the current BOARD to a specctra dsn file.
-     * will export the current BOARD to a specctra dsn file.
+     *
-     * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the
+     * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the specification.
-     * specification.
+     *
      * @return true if OK
      */
     bool ExportSpecctraFile( const wxString& aFullFilename );
 
     /**
-     * Function ImportSpecctraSession
+     * Import a specctra *.ses file and use it to relocate MODULEs and to replace all vias and
-     * will import a specctra *.ses file and use it to relocate MODULEs and
+     * tracks in an existing and loaded #BOARD.
-     * to replace all vias and tracks in an existing and loaded BOARD.
+     *
-     * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the
+     * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the specification.
-     * specification.
      */
     bool ImportSpecctraSession( const wxString& aFullFilename );
 
@@ -727,51 +691,48 @@ public:
     int ShowExchangeFootprintsDialog( FOOTPRINT* aFootprint, bool aUpdateMode, bool aSelectedMode );
 
     /**
-     * Function Exchange_Module
+     * Replace \a aExisting footprint by \a aNew footprint using the \a Existing footprint
-     * Replaces OldModule by NewModule, using OldModule settings:
+     * settings (position, orientation, pad netnames ...).
-     * position, orientation, pad netnames ...)
+     *
-     * OldModule is deleted or put in undo list.
+     * The \a aExisting footprint is deleted or put in undo list.
-     * @param aExisting = footprint to replace
+     *
-     * @param aNew = footprint to put
+     * @param aExisting footprint to replace.
-     * @param aCommit = commit that should store the changes
+     * @param aNew footprint to put.
+     * @param aCommit commit that should store the changes.
      */
     void ExchangeFootprint( FOOTPRINT* aExisting, FOOTPRINT* aNew, BOARD_COMMIT& aCommit,
                             bool deleteExtraTexts = true, bool resetTextLayers = true,
                             bool resetTextEffects = true, bool resetFabricationAttrs = true,
                             bool reset3DModels = true );
 
-    // loading footprints: see PCB_BASE_FRAME
-
     /**
-     * Function OnEditItemRequest
+     * Install the corresponding dialog editor for the given item.
-     * Install the corresponding dialog editor for the given item
+     *
-     * @param aDC = the current device context
+     * @param aDC the current device context.
-     * @param aItem = a pointer to the BOARD_ITEM to edit
+     * @param aItem a pointer to the BOARD_ITEM to edit.
      */
     void OnEditItemRequest( BOARD_ITEM* aItem ) override;
 
     void SwitchLayer( wxDC* DC, PCB_LAYER_ID layer ) override;
 
     /**
-     * Function SetTrackSegmentWidth
      * Modify one track segment width or one via diameter (using DRC control).
+     *
      * Basic routine used by other routines when editing tracks or vias.
      * Note that casting this to boolean will allow you to determine whether any action
      * happened.
-     * @param aTrackItem = the track segment or via to modify
+     *
-     * @param aItemsListPicker = the list picker to use for an undo command
+     * @param aTrackItem the track segment or via to modify.
-     *                           (can be NULL)
+     * @param aItemsListPicker the list picker to use for an undo command (can be NULL).
-     * @param aUseNetclassValue = true to use NetClass value, false to use
+     * @param aUseNetclassValue true to use NetClass value, false to use current designSettings
-     *                            current designSettings value
+     *                          value.
      */
-    void SetTrackSegmentWidth( TRACK*             aTrackItem,
+    void SetTrackSegmentWidth( TRACK* aTrackItem, PICKED_ITEMS_LIST* aItemsListPicker,
-                               PICKED_ITEMS_LIST* aItemsListPicker,
                                bool aUseNetclassValue );
 
 
     /**
-     * Function Edit_Zone_Params
+     * Edit params (layer, clearance, ...) for a zone outline.
-     * Edit params (layer, clearance, ...) for a zone outline
      */
     void Edit_Zone_Params( ZONE* zone_container );
 
@@ -781,93 +742,87 @@ public:
     void InstallNetlistFrame();
 
     /**
-     * Function FetchNetlistFromSchematic
+     * @param aNetlist a #NETLIST owned by the caller.  This function fills it in.
-     * @param aNetlist a NETLIST owned by the caller.  This function fills it in.
      * @return true if a netlist was fetched.
      */
     enum FETCH_NETLIST_MODE { NO_ANNOTATION, QUIET_ANNOTATION, ANNOTATION_DIALOG };
     bool FetchNetlistFromSchematic( NETLIST& aNetlist, FETCH_NETLIST_MODE aMode );
 
     /**
-     * Sends a command to Eeschema to re-annotate the schematic
+     * Send a command to Eeschema to re-annotate the schematic.
-     * @param aNetlist a NETLIST filled in by the caller.
+     *
-     *        aMessage is the error message from eeSchem
+     * @param aNetlist a #NETLIST filled in by the caller.
-     *        if aCommit is false it just test, if true it updates the schematic
      * @return false if failed due to standalone mode, true if a reply.
      */
     bool ReannotateSchematic( std::string& aNetlist );
 
     /**
      * Test if standalone mode.
-     * @return true if in standalone, opens eeSchema, and opens the schematic for this project
+     *
+     * @return true if in standalone, opens Eeschema, and opens the schematic for this project
      */
     bool TestStandalone( void );
 
     /**
-     * Function DoUpdatePCBFromNetlist
      * An automated version of UpdatePCBFromNetlist which skips the UI dialog.
-     * @param aNetlist
-     * @param aUseTimestamps
      */
     void DoUpdatePCBFromNetlist( NETLIST& aNetlist, bool aUseTimestamps );
 
     /**
-     * Reads a netlist from a file into a NETLIST object.
+     * Read a netlist from a file into a #NETLIST object.
      *
-     * @param aFilename is the netlist to load
+     * @param aFilename is the netlist to load.
-     * @param aNetlist is the object to populate with data
+     * @param aNetlist is the object to populate with data.
-     * @param aReporter is a #REPORTER object to display messages
+     * @param aReporter is a #REPORTER object to display messages.
-     * @return true if the netlist was read successfully
+     * @return true if the netlist was read successfully.
      */
     bool ReadNetlistFromFile( const wxString &aFilename, NETLIST& aNetlist, REPORTER& aReporter );
 
     /**
-     * Called after netlist is updated
+     * Called after netlist is updated.
-     * @param aUpdater is the updater object that was run
+     *
-     * @param aRunDragCommand is set to true if the drag command was invoked by this call
+     * @param aUpdater is the updater object that was run.
+     * @param aRunDragCommand is set to true if the drag command was invoked by this call.
      */
     void OnNetlistChanged( BOARD_NETLIST_UPDATER& aUpdater, bool* aRunDragCommand );
 
 
 #if defined( KICAD_SCRIPTING_WXPYTHON )
     /**
-     * Function ScriptingConsoleEnableDisable
+     * Enable or disable the scripting console.
-     * enables or disabled the scripting console
      */
     void ScriptingConsoleEnableDisable();
 #endif
 
     /**
-     * Function SendMessageToEESCHEMA
+     * Send a message to the schematic editor so that it may move its cursor
-     * sends a message to the schematic editor so that it may move its cursor
+     * to a symbol with the same reference as the \a objectToSync.
-     * to a part with the same reference as the objectToSync
+     *
      * @param objectToSync The object whose reference is used to synchronize Eeschema.
      */
     void SendMessageToEESCHEMA( BOARD_ITEM* objectToSync );
 
     /**
-     * Sends a net name to eeschema for highlighting
+     * Send a net name to Eeschema for highlighting.
      *
-     * @param aNetName is the name of a net, or empty string to clear highlight
+     * @param aNetName is the name of a net, or empty string to clear highlight.
      */
     void SendCrossProbeNetName( const wxString& aNetName );
 
     void ShowChangedLanguage() override;
 
     /**
-     * Function UpdateTitle
+     * Set the main window title bar text.
-     * sets the main window title bar text.
+     *
-     * <p>
      * If file name defined by PCB_SCREEN::m_FileName is not set, the title is set to the
      * application name appended with no file.  Otherwise, the title is set to the full path
      * and file name and read only is appended to the title if the user does not have write
      * access to the file.
-     * </p>
      */
     void UpdateTitle();
 
     /**
-     * Allows Pcbnew to install its preferences panel into the preferences dialog.
+     * Allow Pcbnew to install its preferences panel into the preferences dialog.
      */
     void InstallPreferences( PAGED_DIALOG* aParent, PANEL_HOTKEYS_EDITOR* aHotkeysPanel ) override;
 

pcbnew/pcb_painter.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2013 CERN
- * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
@@ -58,15 +59,14 @@ namespace KIGFX
 class GAL;
 
 /**
- * PCB_RENDER_SETTINGS
+ * PCB specific render settings.
- * Stores PCB specific render settings.
  */
 class PCB_RENDER_SETTINGS : public RENDER_SETTINGS
 {
 public:
     friend class PCB_PAINTER;
 
-    ///> Flags to control clearance lines visibility
+    ///< Flags to control clearance lines visibility
     enum CLEARANCE_MODE
     {
         CL_NONE             = 0x00,
@@ -85,9 +85,9 @@ public:
     PCB_RENDER_SETTINGS();
 
     /**
-     * Function LoadDisplayOptions
+     * Load settings related to display options (high-contrast mode, full or outline modes
-     * Loads settings related to display options (high-contrast mode, full or outline modes
      * for vias/pads/tracks and so on).
+     *
      * @param aOptions are settings that you want to use for displaying items.
      */
     void LoadDisplayOptions( const PCB_DISPLAY_OPTIONS& aOptions, bool aShowPageLimits );
@@ -98,8 +98,8 @@ public:
     virtual COLOR4D GetColor( const VIEW_ITEM* aItem, int aLayer ) const override;
 
     /**
-     * Function SetSketchMode
+     * Turn on/off sketch mode for given item layer.
-     * Turns on/off sketch mode for given item layer.
+     *
      * @param aItemLayer is the item layer that is changed.
      * @param aEnabled decides if it is drawn in sketch mode (true for sketched mode,
      *                 false for filled mode).
@@ -110,8 +110,8 @@ public:
     }
 
     /**
-     * Function GetSketchMode
+     * Return sketch mode setting for a given item layer.
-     * Returns sketch mode setting for a given item layer.
+     *
      * @param aItemLayer is the item layer that is changed.
      */
     inline bool GetSketchMode( int aItemLayer ) const
@@ -120,7 +120,8 @@ public:
     }
 
     /**
-     * Turns on/off sketch mode for graphic items (DRAWSEGMENTs, texts).
+     * Turn on/off sketch mode for graphic items (DRAWSEGMENTs, texts).
+     *
      * @param aEnabled decides if it is drawn in sketch mode (true for sketched mode,
      *                 false for filled mode).
      */
@@ -130,7 +131,7 @@ public:
     }
 
     /**
-     * Turns on/off drawing outline and hatched lines for zones.
+     * Turn on/off drawing outline and hatched lines for zones.
      */
     void EnableZoneOutlines( bool aEnabled )
     {
@@ -155,12 +156,14 @@ public:
 
     const COLOR4D& GetCursorColor() override { return m_layerColors[ LAYER_CURSOR ]; }
 
-    /** Switch the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN )
+    /**
+     * Switch the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN )
      * to control how the non active layers are shown
      */
     void SetContrastModeDisplay( HIGH_CONTRAST_MODE aMode ) { m_contrastModeDisplay = aMode; }
 
-    /** return the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN )
+    /**
+     * @return the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN ).
      */
     HIGH_CONTRAST_MODE GetContrastModeDisplay() { return m_contrastModeDisplay; }
 
@@ -187,7 +190,7 @@ public:
     void SetZoneDisplayMode( ZONE_DISPLAY_MODE mode ) { m_zoneDisplayMode = mode; }
 
 protected:
-    ///> Maximum font size for netnames (and other dynamically shown strings)
+    ///< Maximum font size for netnames (and other dynamically shown strings)
     static const double MAX_FONT_SIZE;
 
     bool               m_sketchMode[GAL_LAYER_ID_END];
@@ -212,16 +215,16 @@ protected:
 
     int                m_clearanceDisplayFlags;
 
-    ///> How to display nets and netclasses with color overrides
+    ///< How to display nets and netclasses with color overrides
     NET_COLOR_MODE m_netColorMode;
 
-    ///> Overrides for specific netclass colors
+    ///< Overrides for specific netclass colors
     std::map<wxString, KIGFX::COLOR4D> m_netclassColors;
 
-    ///> Overrides for specific net colors, stored as netcodes for the ratsnest to access easily
+    ///< Overrides for specific net colors, stored as netcodes for the ratsnest to access easily
     std::map<int, KIGFX::COLOR4D> m_netColors;
 
-    ///> Set of net codes that should not have their ratsnest displayed
+    ///< Set of net codes that should not have their ratsnest displayed
     std::set<int> m_hiddenNets;
 
     // These opacity overrides multiply with any opacity in the base layer color
@@ -233,7 +236,6 @@ protected:
 
 
 /**
- * PCB_PAINTER
  * Contains methods for drawing PCB-specific items.
  */
 class PCB_PAINTER : public PAINTER
@@ -273,9 +275,8 @@ protected:
     void draw( const PCB_MARKER* aMarker, int aLayer );
 
     /**
-     * Function getLineThickness()
+     * Get the thickness to draw for a line (e.g. 0 thickness lines get a minimum value).
-     * Get the thickness to draw for a line (e.g. 0 thickness lines
+     *
-     * get a minimum value).
      * @param aActualThickness line own thickness
      * @return the thickness to draw
      */

pcbnew/pcbnew_printout.h

@@ -1,7 +1,8 @@
 /*
- * Copyright (C) 1992-2016 KiCad Developers, see AUTHORS.txt for contributors.
  * Copyright (C) 2018 CERN
- * Author: Maciej Suminski <maciej.suminski@cern.ch>
+ * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
+ * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -77,9 +78,9 @@ private:
 
 
 namespace KIGFX {
+
 /**
- * Special flavor of PCB_PAINTER that contains
+ * Special flavor of PCB_PAINTER that contains modifications to handle printing options.
- * modifications to handle printing options.
  */
 class PCB_PRINT_PAINTER : public PCB_PAINTER
 {
@@ -88,6 +89,7 @@ public:
 
     /**
      * Set drill marks visibility and options.
+     *
      * @param aRealSize when enabled, drill marks represent actual holes. Otherwise aSize
      *                  parameter is used.
      * @param aSize is drill mark size (internal units), valid only when aRealSize == false.
@@ -105,10 +107,10 @@ protected:
 
     int getDrillSize( const VIA* aVia ) const override;
 
-    ///> Flag deciding whether use the actual hole size or user-specified size for drill marks
+    ///< Flag deciding whether use the actual hole size or user-specified size for drill marks
     bool m_drillMarkReal;
 
-    ///> User-specified size for drill marks (expressed in internal units)
+    ///< User-specified size for drill marks (expressed in internal units)
     int m_drillMarkSize;
 };
 

pcbnew/plugins/eagle/eagle_plugin.h

@@ -5,7 +5,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
- * Copyright (C) 2012-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -47,6 +47,38 @@ typedef NET_MAP::const_iterator         NET_MAP_CITER;
 /// subset of eagle.drawing.board.designrules in the XML document
 struct ERULES
 {
+    ERULES() :
+        psElongationLong    ( 100 ),
+        psElongationOffset  ( 0 ),
+
+        mvStopFrame         ( 1.0 ),
+        mvCreamFrame        ( 0.0 ),
+        mlMinStopFrame      ( Mils2iu( 4.0 ) ),
+        mlMaxStopFrame      ( Mils2iu( 4.0 ) ),
+        mlMinCreamFrame     ( Mils2iu( 0.0 ) ),
+        mlMaxCreamFrame     ( Mils2iu( 0.0 ) ),
+
+        psTop               ( EPAD::UNDEF ),
+        psBottom            ( EPAD::UNDEF ),
+        psFirst             ( EPAD::UNDEF ),
+
+        srRoundness         ( 0.0 ),
+        srMinRoundness      ( Mils2iu( 0.0 ) ),
+        srMaxRoundness      ( Mils2iu( 0.0 ) ),
+
+        rvPadTop            ( 0.25 ),
+        // rvPadBottom      ( 0.25 ),
+        rlMinPadTop         ( Mils2iu( 10 ) ),
+        rlMaxPadTop         ( Mils2iu( 20 ) ),
+
+        rvViaOuter          ( 0.25 ),
+        rlMinViaOuter       ( Mils2iu( 10 ) ),
+        rlMaxViaOuter       ( Mils2iu( 20 ) ),
+        mdWireWire          ( 0 )
+    {}
+
+    void parse( wxXmlNode* aRules );
+
     ///< percent over 100%.  0-> not elongated, 100->twice as wide as is tall
     ///< Goes into making a scaling factor for "long" pads.
     int    psElongationLong;
@@ -85,39 +117,6 @@ struct ERULES
     double rlMinViaOuter;       ///< minimum copper annulus on via
     double rlMaxViaOuter;       ///< maximum copper annulus on via
     double mdWireWire;          ///< wire to wire spacing I presume.
-
-
-    ERULES() :
-        psElongationLong    ( 100 ),
-        psElongationOffset  ( 0 ),
-
-        mvStopFrame         ( 1.0 ),
-        mvCreamFrame        ( 0.0 ),
-        mlMinStopFrame      ( Mils2iu( 4.0 ) ),
-        mlMaxStopFrame      ( Mils2iu( 4.0 ) ),
-        mlMinCreamFrame     ( Mils2iu( 0.0 ) ),
-        mlMaxCreamFrame     ( Mils2iu( 0.0 ) ),
-
-        psTop               ( EPAD::UNDEF ),
-        psBottom            ( EPAD::UNDEF ),
-        psFirst             ( EPAD::UNDEF ),
-
-        srRoundness         ( 0.0 ),
-        srMinRoundness      ( Mils2iu( 0.0 ) ),
-        srMaxRoundness      ( Mils2iu( 0.0 ) ),
-
-        rvPadTop            ( 0.25 ),
-        // rvPadBottom      ( 0.25 ),
-        rlMinPadTop         ( Mils2iu( 10 ) ),
-        rlMaxPadTop         ( Mils2iu( 20 ) ),
-
-        rvViaOuter          ( 0.25 ),
-        rlMinViaOuter       ( Mils2iu( 10 ) ),
-        rlMaxViaOuter       ( Mils2iu( 20 ) ),
-        mdWireWire          ( 0 )
-    {}
-
-    void parse( wxXmlNode* aRules );
 };
 
 
@@ -172,38 +171,6 @@ public:
             const std::vector<INPUT_LAYER_DESC>& aInputLayerDescriptionVector );
 
 private:
-    typedef std::vector<ELAYER>     ELAYERS;
-    typedef ELAYERS::const_iterator EITER;
-
-    int                              m_cu_map[17];     ///< map eagle to KiCad, cu layers only.
-    std::map<int, ELAYER>            m_eagleLayers;    ///< Eagle layer data stored by layer number
-    std::map<wxString, int>          m_eagleLayersIds; ///< Eagle layer ids stored by layer name
-    std::map<wxString, PCB_LAYER_ID> m_layer_map;      ///< Map of Eagle layers to KiCad layers
-
-    ERULES*       m_rules;          ///< Eagle design rules.
-    XPATH*        m_xpath;          ///< keeps track of what we are working on within
-                                    ///< XML document during a Load().
-
-    int           m_hole_count;     ///< generates unique footprint names from eagle "hole"s.
-
-    NET_MAP       m_pads_to_nets;   ///< net list
-
-    FOOTPRINT_MAP m_templates;      ///< is part of a FOOTPRINT factory that operates using copy
-                                    ///< construction.
-                                    ///< lookup key is either libname.packagename or simply
-                                    ///< packagename if FootprintLoad() or FootprintEnumberate()
-
-    const PROPERTIES* m_props;      ///< passed via Save() or Load(), no ownership, may be NULL.
-    BOARD*      m_board;            ///< which BOARD is being worked on, no ownership here
-
-    int         m_min_trace;        ///< smallest trace we find on Load(), in BIU.
-    int         m_min_hole;         ///< smallest diameter hole we find on Load(), in BIU.
-    int         m_min_via;          ///< smallest via we find on Load(), in BIU.
-    int         m_min_annulus;      ///< smallest via annulus we find on Load(), in BIU.
-
-    wxString    m_lib_path;
-    wxDateTime  m_mod_time;
-
     /// initialize PLUGIN like a constructor would, and futz with fresh BOARD if needed.
     void    init( const PROPERTIES* aProperties );
 
@@ -216,13 +183,13 @@ private:
     /// create a font size (fontz) from an eagle font size scalar and KiCad font thickness
     wxSize  kicad_fontz( const ECOORD& d, int aTextThickness ) const;
 
-    /// Generate mapping between Eagle na KiCAD layers
+    /// Generate mapping between Eagle na KiCad layers
     void mapEagleLayersToKicad();
 
     /// Convert an Eagle layer to a KiCad layer.
     PCB_LAYER_ID kicad_layer( int aLayer ) const;
 
-    /// Get default KiCAD layer corresponding to an Eagle layer of the board,
+    /// Get default KiCad layer corresponding to an Eagle layer of the board,
     /// a set of sensible layer mapping options and required flag
     std::tuple<PCB_LAYER_ID, LSET, bool> defaultKicadLayer( int aEagleLayer ) const;
 
@@ -298,11 +265,43 @@ private:
     void packageHole( FOOTPRINT* aFootprint, wxXmlNode* aTree, bool aCenter ) const;
     void packageSMD( FOOTPRINT* aFootprint, wxXmlNode* aTree ) const;
 
-    ///> Handles common pad properties
+    ///< Handles common pad properties
     void transferPad( const EPAD_COMMON& aEaglePad, PAD* aPad ) const;
 
-    ///> Deletes the footprint templates list
+    ///< Deletes the footprint templates list
     void deleteTemplates();
+
+    typedef std::vector<ELAYER>     ELAYERS;
+    typedef ELAYERS::const_iterator EITER;
+
+    int                              m_cu_map[17];     ///< map eagle to KiCad, cu layers only.
+    std::map<int, ELAYER>            m_eagleLayers;    ///< Eagle layer data stored by layer number
+    std::map<wxString, int>          m_eagleLayersIds; ///< Eagle layer ids stored by layer name
+    std::map<wxString, PCB_LAYER_ID> m_layer_map;      ///< Map of Eagle layers to KiCad layers
+
+    ERULES*       m_rules;          ///< Eagle design rules.
+    XPATH*        m_xpath;          ///< keeps track of what we are working on within
+                                    ///< XML document during a Load().
+
+    int           m_hole_count;     ///< generates unique footprint names from eagle "hole"s.
+
+    NET_MAP       m_pads_to_nets;   ///< net list
+
+    FOOTPRINT_MAP m_templates;      ///< is part of a FOOTPRINT factory that operates using copy
+                                    ///< construction.
+                                    ///< lookup key is either libname.packagename or simply
+                                    ///< packagename if FootprintLoad() or FootprintEnumberate()
+
+    const PROPERTIES* m_props;      ///< passed via Save() or Load(), no ownership, may be NULL.
+    BOARD*      m_board;            ///< which BOARD is being worked on, no ownership here
+
+    int         m_min_trace;        ///< smallest trace we find on Load(), in BIU.
+    int         m_min_hole;         ///< smallest diameter hole we find on Load(), in BIU.
+    int         m_min_via;          ///< smallest via we find on Load(), in BIU.
+    int         m_min_annulus;      ///< smallest via annulus we find on Load(), in BIU.
+
+    wxString    m_lib_path;
+    wxDateTime  m_mod_time;
 };
 
 #endif  // EAGLE_PLUGIN_H_

pcbnew/plugins/kicad/pcb_parser.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2012 CERN
- * Copyright (C) 2012-2019 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -62,44 +62,71 @@ struct LAYER;
 
 
 /**
- * PCB_PARSER
+ * Read a Pcbnew s-expression formatted #LINE_READER object and returns the appropriate
- * reads a Pcbnew s-expression formatted #LINE_READER object and returns the appropriate
  * #BOARD_ITEM object.
  */
 class PCB_PARSER : public PCB_LEXER
 {
-    typedef std::unordered_map< std::string, PCB_LAYER_ID > LAYER_ID_MAP;
+public:
-    typedef std::unordered_map< std::string, LSET >         LSET_MAP;
+    PCB_PARSER( LINE_READER* aReader = NULL ) :
-    typedef std::unordered_map< wxString, KIID >            KIID_MAP;
+        PCB_LEXER( aReader ),
-
+        m_board( nullptr ),
-    BOARD*              m_board;
+        m_resetKIIDs( false )
-    LAYER_ID_MAP        m_layerIndices;     ///< map layer name to it's index
-    LSET_MAP            m_layerMasks;       ///< map layer names to their masks
-    std::set<wxString>  m_undefinedLayers;  ///< set of layers not defined in layers section
-    std::vector<int>    m_netCodes;         ///< net codes mapping for boards being loaded
-    bool                m_tooRecent;        ///< true if version parses as later than supported
-    int                 m_requiredVersion;  ///< set to the KiCad format version this board requires
-    bool                m_resetKIIDs;       ///< reading into an existing board; reset UUIDs
-    KIID_MAP            m_resetKIIDMap;     ///< if resetting UUIDs, record new ones to update groups with
-
-    bool                m_showLegacyZoneWarning;
-
-    // Group membership info refers to other Uuids in the file.
-    // We don't want to rely on group declarations being last in the file, so
-    // we store info about the group declarations here during parsing and then resolve
-    // them into BOARD_ITEM* after we've parsed the rest of the file.
-    typedef struct
     {
-        BOARD_ITEM*       parent;
+        init();
-        wxString          name;
+    }
-        KIID              uuid;
-        std::vector<KIID> memberUuids;
-    } GROUP_INFO;
 
-    std::vector<GROUP_INFO> m_groupInfos;
+    // ~PCB_PARSER() {}
 
-    ///> Converts net code using the mapping table if available,
+    /**
-    ///> otherwise returns unchanged net code if < 0 or if is is out of range
+     * Set @a aLineReader into the parser, and returns the previous one, if any.
+     *
+     * @param aReader is what to read from for tokens, no ownership is received.
+     * @return LINE_READER* - previous LINE_READER or NULL if none.
+     */
+    LINE_READER* SetLineReader( LINE_READER* aReader )
+    {
+        LINE_READER* ret = PopReader();
+        PushReader( aReader );
+        return ret;
+    }
+
+    void SetBoard( BOARD* aBoard )
+    {
+        init();
+        m_board = aBoard;
+
+        if( aBoard != nullptr )
+            m_resetKIIDs = true;
+    }
+
+    BOARD_ITEM* Parse();
+
+    /**
+     * @param aInitialComments may be a pointer to a heap allocated initial comment block
+     *                         or NULL.  If not NULL, then caller has given ownership of a
+     *                         wxArrayString to this function and care must be taken to
+     *                         delete it even on exception.
+     */
+    FOOTPRINT* parseFOOTPRINT( wxArrayString* aInitialComments = 0 );
+
+    /**
+     * Return whether a version number, if any was parsed, was too recent
+     */
+    bool IsTooRecent()
+    {
+        return m_tooRecent;
+    }
+
+    /**
+     * Return a string representing the version of KiCad required to open this
+     * file. Not particularly meaningful if IsTooRecent() returns false.
+     */
+    wxString GetRequiredVersion();
+
+private:
+    ///< Convert net code using the mapping table if available,
+    ///< otherwise returns unchanged net code if < 0 or if is is out of range
     inline int getNetCode( int aNetCode )
     {
         if( ( aNetCode >= 0 ) && ( aNetCode < (int) m_netCodes.size() ) )
@@ -109,34 +136,35 @@ class PCB_PARSER : public PCB_LEXER
     }
 
     /**
-     * function pushValueIntoMap
+     * Add aValue value in netcode mapping (m_netCodes) at \a aIndex.
-     * Add aValue value in netcode mapping (m_netCodes) at index aIndex
+     *
-     * ensure there is room in m_netCodes for that, and add room if needed.
+     * Ensure there is room in m_netCodes for that, and add room if needed.
-     * @param aIndex = the index ( expected >=0 )of the location to use in m_netCodes
+     *
-     * @param aValue = the netcode value to map
+     * @param aIndex is the index ( expected >=0 )of the location to use in m_netCodes.
+     * @param aValue is the netcode value to map.
      */
     void pushValueIntoMap( int aIndex, int aValue );
 
     /**
-     * Function init
+     * Clear and re-establish m_layerMap with the default layer names.
-     * clears and re-establishes m_layerMap with the default layer names.
+     *
      * m_layerMap will have some of its entries overwritten whenever a (new) board
      * is encountered.
      */
     void init();
 
     /**
-     * Creates a mapping from the (short-lived) bug where layer names were translated
+     * Create a mapping from the (short-lived) bug where layer names were translated.
-     * TODO: Remove this once we support custom layer names
      *
-     * @param aMap string mapping from translated to English layer names
+     * @todo Remove this once we support custom layer names.
+     *
+     * @param aMap string mapping from translated to English layer names.
      */
     void createOldLayerMapping( std::unordered_map< std::string, std::string >& aMap );
 
     /**
-     * Function skipCurrent
+     * Skip the current token level, i.e search for the RIGHT parenthesis which closes the
-     * Skip the current token level, i.e
+     * current description.
-     * search for the RIGHT parenthesis which closes the current description
      */
     void skipCurrent();
 
@@ -182,48 +210,43 @@ class PCB_PARSER : public PCB_LEXER
     BOARD*          parseBOARD_unchecked();
 
     /**
-     * Function lookUpLayer
+     * Parse the current token for the layer definition of a #BOARD_ITEM object.
-     * parses the current token for the layer definition of a #BOARD_ITEM object.
      *
      * @param aMap is the LAYER_{NUM|MSK}_MAP to use for the lookup.
-     *
+     * @return The result of the parsed #BOARD_ITEM layer or set designator.
      * @throw IO_ERROR if the layer is not valid.
      * @throw PARSE_ERROR if the layer syntax is incorrect.
-     * @return int - The result of the parsed #BOARD_ITEM layer or set designator.
      */
     template<class T, class M>
     T lookUpLayer( const M& aMap );
 
     /**
-     * Function parseBoardItemLayer
+     * Parse the layer definition of a #BOARD_ITEM object.
-     * parses the layer definition of a #BOARD_ITEM object.
      *
+     * @return The index the parsed #BOARD_ITEM layer.
      * @throw IO_ERROR if the layer is not valid.
      * @throw PARSE_ERROR if the layer syntax is incorrect.
-     * @return The index the parsed #BOARD_ITEM layer.
      */
     PCB_LAYER_ID parseBoardItemLayer();
 
     /**
-     * Function parseBoardItemLayersAsMask
+     * Parse the layers definition of a #BOARD_ITEM object.
-     * parses the layers definition of a #BOARD_ITEM object.
      *
+     * @return The mask of layers the parsed #BOARD_ITEM is on.
      * @throw IO_ERROR if any of the layers is not valid.
      * @throw PARSE_ERROR if the layers syntax is incorrect.
-     * @return The mask of layers the parsed #BOARD_ITEM is on.
      */
     LSET parseBoardItemLayersAsMask();
 
     /**
-     * Function parseXY
+     * Parse a coordinate pair (xy X Y) in board units (mm).
-     * parses a coordinate pair (xy X Y) in board units (mm).
      *
      * The parser checks if the previous token was T_LEFT and parses the remainder of
      * the token syntax.  This is used when parsing a list of coordinate points.  This
      * way the parser can be used in either case.
      *
-     * @throw PARSE_ERROR if the coordinate pair syntax is incorrect.
      * @return A wxPoint object containing the coordinate pair.
+     * @throw PARSE_ERROR if the coordinate pair syntax is incorrect.
      */
     wxPoint parseXY();
 
@@ -232,23 +255,21 @@ class PCB_PARSER : public PCB_LEXER
     std::pair<wxString, wxString> parseProperty();
 
     /**
-     * Function parseEDA_TEXT
+     * Parse the common settings for any object derived from #EDA_TEXT.
-     * parses the common settings for any object derived from #EDA_TEXT.
      *
-     * @throw PARSE_ERROR if the text syntax is not valid.
      * @param aText A point to the #EDA_TEXT object to save the parsed settings into.
+     * @throw PARSE_ERROR if the text syntax is not valid.
      */
     void parseEDA_TEXT( EDA_TEXT* aText );
 
     FP_3DMODEL* parse3DModel();
 
     /**
-     * Function parseDouble
+     * Parse the current token as an ASCII numeric string with possible leading
-     * parses the current token as an ASCII numeric string with possible leading
      * whitespace into a double precision floating point number.
      *
-     * @throw IO_ERROR if an error occurs attempting to convert the current token.
      * @return The result of the parsed token.
+     * @throw IO_ERROR if an error occurs attempting to convert the current token.
      */
     double parseDouble();
 
@@ -290,9 +311,8 @@ class PCB_PARSER : public PCB_LEXER
         // the system.  We limit values to the largest that is visible on the screen
         double int_limit = std::numeric_limits<int>::max() * 0.7071;
 
-        // Use here KiROUND, not KIROUND (see comments about them)
+        // Use here #KiROUND, not EKIROUND (see comments about them) when having a function as
-        // when having a function as argument, because it will be called twice
+        // argument, because it will be called twice with #KIROUND.
-        // with KIROUND
         return KiROUND( Clamp<double>( -int_limit, retval, int_limit ) );
     }
 
@@ -321,7 +341,7 @@ class PCB_PARSER : public PCB_LEXER
     bool parseBool();
 
     /*
-     * @return if m_resetKIIDs, returns new KIID(), otehrwise returns CurStr() as KIID.
+     * @return if m_resetKIIDs, returns new KIID(), otherwise returns CurStr() as KIID.
      */
     KIID CurStrToKIID();
 
@@ -331,63 +351,37 @@ class PCB_PARSER : public PCB_LEXER
      */
     void resolveGroups( BOARD_ITEM* aParent );
 
-public:
+    typedef std::unordered_map< std::string, PCB_LAYER_ID > LAYER_ID_MAP;
+    typedef std::unordered_map< std::string, LSET >         LSET_MAP;
+    typedef std::unordered_map< wxString, KIID >            KIID_MAP;
 
-    PCB_PARSER( LINE_READER* aReader = NULL ) :
+    BOARD*              m_board;
-        PCB_LEXER( aReader ),
+    LAYER_ID_MAP        m_layerIndices;     ///< map layer name to it's index
-        m_board( nullptr ),
+    LSET_MAP            m_layerMasks;       ///< map layer names to their masks
-        m_resetKIIDs( false )
+    std::set<wxString>  m_undefinedLayers;  ///< set of layers not defined in layers section
+    std::vector<int>    m_netCodes;         ///< net codes mapping for boards being loaded
+    bool                m_tooRecent;        ///< true if version parses as later than supported
+    int                 m_requiredVersion;  ///< set to the KiCad format version this board requires
+    bool                m_resetKIIDs;       ///< reading into an existing board; reset UUIDs
+
+    ///< if resetting UUIDs, record new ones to update groups with.
+    KIID_MAP            m_resetKIIDMap;
+
+    bool                m_showLegacyZoneWarning;
+
+    // Group membership info refers to other Uuids in the file.
+    // We don't want to rely on group declarations being last in the file, so
+    // we store info about the group declarations here during parsing and then resolve
+    // them into BOARD_ITEM* after we've parsed the rest of the file.
+    typedef struct
     {
-        init();
+        BOARD_ITEM*       parent;
-    }
+        wxString          name;
-
+        KIID              uuid;
-    // ~PCB_PARSER() {}
+        std::vector<KIID> memberUuids;
-
+    } GROUP_INFO;
-    /**
-     * Function SetLineReader
-     * sets @a aLineReader into the parser, and returns the previous one, if any.
-     * @param aReader is what to read from for tokens, no ownership is received.
-     * @return LINE_READER* - previous LINE_READER or NULL if none.
-     */
-    LINE_READER* SetLineReader( LINE_READER* aReader )
-    {
-        LINE_READER* ret = PopReader();
-        PushReader( aReader );
-        return ret;
-    }
-
-    void SetBoard( BOARD* aBoard )
-    {
-        init();
-        m_board = aBoard;
-
-        if( aBoard != nullptr )
-            m_resetKIIDs = true;
-    }
-
-    BOARD_ITEM* Parse();
-    /**
-     * Function parseFOOTPRINT
-     * @param aInitialComments may be a pointer to a heap allocated initial comment block
-     *   or NULL.  If not NULL, then caller has given ownership of a wxArrayString to
-     *   this function and care must be taken to delete it even on exception.
-     */
-    FOOTPRINT* parseFOOTPRINT( wxArrayString* aInitialComments = 0 );
-
-    /**
-     * Return whether a version number, if any was parsed, was too recent
-     */
-    bool IsTooRecent()
-    {
-        return m_tooRecent;
-    }
-
-    /**
-     * Return a string representing the version of kicad required to open this
-     * file. Not particularly meaningful if IsTooRecent() returns false.
-     */
-    wxString GetRequiredVersion();
 
+    std::vector<GROUP_INFO> m_groupInfos;
 };
 
 

pcbnew/plugins/legacy/legacy_plugin.h

@@ -5,7 +5,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
- * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -55,6 +55,7 @@ struct LP_CACHE;
 
 /**
  * A #PLUGIN derivation which could possibly be put into a DLL/DSO.
+ *
  * As with any PLUGIN, there is no UI, i.e. windowing calls allowed.
  */
 class LEGACY_PLUGIN : public PLUGIN
@@ -101,8 +102,8 @@ public:
     static LSET leg_mask2new( int cu_count, unsigned aMask );
 
 protected:
-    ///> Converts net code using the mapping table if available,
+    ///< Converts net code using the mapping table if available,
-    ///> otherwise returns unchanged net code
+    ///< otherwise returns unchanged net code
     inline int getNetCode( int aNetCode )
     {
         if( (unsigned int) aNetCode < m_netCodes.size() )
@@ -115,7 +116,7 @@ protected:
      * Parse an ASCII decimal floating point value and scales it into a BIU according to the
      * current value of diskToBui.
      *
-     * This fuction is the complement of #fmtBIU().  One has to know what the other is doing.
+     * This function is the complement of #fmtBIU().  One has to know what the other is doing.
      *
      * @param aValue is the ASCII value in C locale form with possible leading whitespace
      * @param nptrptr may be NULL, but if not, then it tells where to put a pointer to the

pcbnew/ratsnest/ratsnest_data.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2013-2015 CERN
- * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -55,26 +56,23 @@ struct CN_PTR_CMP
 };
 
 /**
- * RN_NET
+ * Describe ratsnest for a single net.
- * Describes ratsnest for a single net.
  */
 class RN_NET
 {
 public:
-    ///> Default constructor.
     RN_NET();
 
     /**
-     * Function SetVisible()
+     * Set state of the visibility flag.
-     * Sets state of the visibility flag.
+     *
      * @param aEnabled is new state. True if ratsnest for a given net is meant to be displayed,
      *                 false otherwise.
      */
     void SetVisible( bool aEnabled );
 
     /**
-     * Function MarkDirty()
+     * Mark ratsnest for given net as 'dirty', i.e. requiring recomputation.
-     * Marks ratsnest for given net as 'dirty', i.e. requiring recomputation.
      */
     void MarkDirty()
     {
@@ -82,9 +80,9 @@ public:
     }
 
     /**
-     * Function IsDirty()
+     * Return state of the 'dirty' flag, indicating that ratsnest for a given net is invalid
-     * Returns state of the 'dirty' flag, indicating that ratsnest for a given net is invalid
      * and requires an update.
+     *
      * @return True if ratsnest requires recomputation, false otherwise.
      */
     bool IsDirty() const
@@ -93,8 +91,8 @@ public:
     }
 
     /**
-     * Function GetUnconnected()
+     * Return pointer to a vector of edges that makes ratsnest for a given net.
-     * Returns pointer to a vector of edges that makes ratsnest for a given net.
+     *
      * @return Pointer to a vector of edges that makes ratsnest for a given net.
      */
     const std::vector<CN_EDGE> GetUnconnected() const
@@ -103,8 +101,7 @@ public:
     }
 
     /**
-     * Function Update()
+     * Recompute ratsnest for a net.
-     * Recomputes ratsnest for a net.
      */
     void Update();
     void Clear();
@@ -117,8 +114,8 @@ public:
     }
 
     /**
-     * Function GetNodes()
+     * Return list of nodes that are associated with a given item.
-     * Returns list of nodes that are associated with a given item.
+     *
      * @param aItem is an item for which the list is generated.
      * @return List of associated nodes.
      */
@@ -130,39 +127,40 @@ public:
     }
 
     /**
-     * Function GetAllItems()
+     * Add all stored items to a list.
-     * Adds all stored items to a list.
+     *
      * @param aOutput is the list that will have items added.
      * @param aTypes determines the type of added items.
      */
     void GetAllItems( std::list<BOARD_CONNECTED_ITEM*>& aOutput, const KICAD_T aTypes[] ) const;
 
     /**
-     * Function GetClosestNode()
+     * Return a single node that lies in the shortest distance from a specific node.
-     * Returns a single node that lies in the shortest distance from a specific node.
+     *
      * @param aNode is the node for which the closest node is searched.
      */
     const CN_ANCHOR_PTR GetClosestNode( const CN_ANCHOR_PTR& aNode ) const;
 
-    bool NearestBicoloredPair( const RN_NET& aOtherNet, CN_ANCHOR_PTR& aNode1, CN_ANCHOR_PTR& aNode2 ) const;
+    bool NearestBicoloredPair( const RN_NET& aOtherNet, CN_ANCHOR_PTR& aNode1,
+                               CN_ANCHOR_PTR& aNode2 ) const;
 
 protected:
-    ///> Recomputes ratsnest from scratch.
+    ///< Recompute ratsnest from scratch.
     void compute();
 
-    ///> Compute the minimum spanning tree using Kruskal's algorithm
+    ///< Compute the minimum spanning tree using Kruskal's algorithm
     void kruskalMST( const std::vector<CN_EDGE> &aEdges );
 
-    ///> Vector of nodes
+    ///< Vector of nodes
     std::multiset<CN_ANCHOR_PTR, CN_PTR_CMP> m_nodes;
 
-    ///> Vector of edges that make pre-defined connections
+    ///< Vector of edges that make pre-defined connections
     std::vector<CN_EDGE> m_boardEdges;
 
-    ///> Vector of edges that makes ratsnest for a given net.
+    ///< Vector of edges that makes ratsnest for a given net.
     std::vector<CN_EDGE> m_rnEdges;
 
-    ///> Flag indicating necessity of recalculation of ratsnest for a net.
+    ///< Flag indicating necessity of recalculation of ratsnest for a net.
     bool m_dirty;
 
     class TRIANGULATOR_STATE;

pcbnew/ratsnest/ratsnest_viewitem.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KICAD, a free EDA CAD application.
  *
  * Copyright (C) 2013 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -63,7 +65,9 @@ public:
     void Show( int x, std::ostream& st ) const override { }
 #endif
 
-    /** Get class name
+    /**
+     * Get class name.
+     *
      * @return string "RATSNEST_VIEWITEM"
      */
     virtual wxString GetClass() const override
@@ -72,7 +76,7 @@ public:
     }
 
 protected:
-    ///> Object containing ratsnest data.
+    ///< Object containing ratsnest data.
     std::shared_ptr<CONNECTIVITY_DATA> m_data;
 };
 

pcbnew/router/pns_algo_base.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -31,10 +32,10 @@ class LOGGER;
 class DEBUG_DECORATOR;
 
 /**
- * ALGO_BASE
+ * Base class for all P&S algorithms (shoving, walkaround, line placement, dragging, etc.).
  *
- * Base class for all P&S algorithms (shoving, walkaround, line placement, dragging, etc.)
+ * Holds a bunch of objects commonly used by all algorithms (P&S settings, parent router
- * Holds a bunch of objects commonly used by all algorithms (P&S settings, parent router instance, logging)
+ * instance, logging).
  */
 class ALGO_BASE
 {
@@ -47,16 +48,16 @@ public:
 
     virtual ~ALGO_BASE() {}
 
-    ///> Returns the instance of our router
+    ///< Return the instance of our router
     ROUTER* Router() const
     {
         return m_router;
     }
 
-    ///> Returns current router settings
+    ///< Return current router settings
     ROUTING_SETTINGS& Settings() const;
 
-    ///> Returns the logger object, allowing to dump geometry to a file.
+    ///< Return the logger object, allowing to dump geometry to a file.
     virtual LOGGER* Logger();
 
     void SetLogger( LOGGER* aLogger )
@@ -65,9 +66,7 @@ public:
     }
 
     /**
-    * Function SetDebugDecorator
+     * Assign a debug decorator allowing this algo to draw extra graphics for visual debugging.
-    *
-    * Assign a debug decorator allowing this algo to draw extra graphics for visual debugging
      */
     void SetDebugDecorator( DEBUG_DECORATOR* aDecorator )
     {

pcbnew/router/pns_diff_pair_placer.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -46,10 +47,9 @@ class SIZES_SETTINGS;
 
 
 /**
- * LINE_PLACER
+ * Single track placement algorithm.
  *
- * Single track placement algorithm. Interactively routes a track.
+ * Interactively routes a track and applies shove and walk around algorithms when needed.
- * Applies shove and walkaround algorithms when needed.
  */
 
 class DIFF_PAIR_PLACER : public PLACEMENT_ALGO
@@ -62,30 +62,23 @@ public:
                                      DP_PRIMITIVE_PAIR& aPair, wxString* aErrorMsg = nullptr );
 
     /**
-     * Function Start()
+     * Start routing a single track at point aP, taking item aStartItem as anchor (unless NULL).
-     *
-     * Starts routing a single track at point aP, taking item aStartItem as anchor
-     * (unless NULL).
      */
     bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override;
 
     /**
-     * Function Move()
+     * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as
-     *
+     * anchor (if not NULL).
-     * Moves the end of the currently routed trace to the point aP, taking
-     * aEndItem as anchor (if not NULL).
-     * (unless NULL).
      */
     bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override;
 
     /**
-     * Function FixRoute()
+     * Commit the currently routed track to the parent node, taking \a aP as the final end
+     * point and \a aEndItem as the final anchor (if provided).
      *
-     * Commits the currently routed track to the parent node, taking
+     * @return true if route has been committed. May return false if the routing result is
-     * aP as the final end point and aEndItem as the final anchor (if provided).
+     *         violating design rules.  In such cases, the track is only committed if
-     * @return true, if route has been commited. May return false if the routing
+     *         #Settings.CanViolateDRC() is on.
-     * result is violating design rules - in such case, the track is only committed
-     * if Settings.CanViolateDRC() is on.
      */
     bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish ) override;
 
@@ -99,31 +92,23 @@ public:
     bool HasPlacedAnything() const override;
 
     /**
-     * Function ToggleVia()
+     * Enable/disable a via at the end of currently routed trace.
-     *
-     * Enables/disables a via at the end of currently routed trace.
      */
     bool ToggleVia( bool aEnabled ) override;
 
     /**
-     * Function SetLayer()
+     * Set the current routing layer.
-     *
-     * Sets the current routing layer.
      */
     bool SetLayer( int aLayer ) override;
 
     /**
-     * Function Traces()
+     * Return the complete routed line, as a single-member ITEM_SET.
-     *
-     * Returns the complete routed line, as a single-member ITEM_SET.
      */
     const ITEM_SET Traces() override;
 
     /**
-     * Function CurrentEnd()
+     * Return the current end of the line being placed. It may not be equal to the cursor
-     *
+     * position due to collisions.
-     * Returns the current end of the line being placed. It may not be equal
-     * to the cursor position due to collisions.
      */
     const VECTOR2I& CurrentEnd() const override
     {
@@ -131,16 +116,12 @@ public:
     }
 
     /**
-     * Function CurrentNets()
+     * Return the net code of currently routed track.
-     *
-     * Returns the net code of currently routed track.
      */
     const std::vector<int> CurrentNets() const override;
 
     /**
-     * Function CurrentLayer()
+     * Return the layer of currently routed track.
-     *
-     * Returns the layer of currently routed track.
      */
     int CurrentLayer() const override
     {
@@ -148,25 +129,19 @@ public:
     }
 
     /**
-     * Function CurrentNode()
+     * Return the most recent world state.
-     *
-     * Returns the most recent world state.
      */
     NODE* CurrentNode( bool aLoopsRemoved = false ) const override;
 
     /**
-     * Function FlipPosture()
+     * Toggle the current posture (straight/diagonal) of the trace head.
-     *
-     * Toggles the current posture (straight/diagonal) of the trace head.
      */
     void FlipPosture() override;
 
     /**
-     * Function UpdateSizes()
+     * Perform on-the-fly update of the width, via diameter & drill size from a settings class.
      *
-     * Performs on-the-fly update of the width, via diameter & drill size from
+     * Used to dynamically change these parameters as the track is routed.
-     * a settings class. Used to dynamically change these parameters as
-     * the track is routed.
      */
     void UpdateSizes( const SIZES_SETTINGS& aSizes ) override;
 
@@ -181,44 +156,36 @@ private:
     int gap() const;
 
     /**
-     * Function route()
+     * Re-route the current track to point \a aP.
      *
-     * Re-routes the current track to point aP. Returns true, when routing has
+     * Returns true, when routing has completed successfully (i.e. the trace end has reached
-     * completed successfully (i.e. the trace end has reached point aP), and false
+     * point aP), and false if the trace was stuck somewhere on the way.  May call routeStep()
-     * if the trace was stuck somewhere on the way. May call routeStep()
      * repetitively due to mouse smoothing.
-     * @param aP ending point of current route.
+     *
-     * @return true, if the routing is complete.
+     * @param aP is the ending point of current route.
+     * @return true if the routing is complete.
      */
     bool route( const VECTOR2I& aP );
 
     /**
-     * Function updateLeadingRatLine()
+     * Draw the "leading" ratsnest line, which connects the end of currently routed track and
-     *
+     * the nearest yet unrouted item. If the routing for current net is complete, draws nothing.
-     * Draws the "leading" ratsnest line, which connects the end of currently
-     * routed track and the nearest yet unrouted item. If the routing for
-     * current net is complete, draws nothing.
      */
     void updateLeadingRatLine();
 
     /**
-     * Function setWorld()
+     * Set the board to route.
-     *
-     * Sets the board to route.
      */
     void setWorld( NODE* aWorld );
 
     /**
-     * Function startPlacement()
+     * Initialize placement of a new line with given parameters.
-     *
-     * Initializes placement of a new line with given parameters.
      */
     void initPlacement( );
 
     /**
-     * Function setInitialDirection()
+     * Set preferred direction of the very first track segment to be laid.
      *
-     * Sets preferred direction of the very first track segment to be laid.
      * Used by posture switching mechanism.
      */
     void setInitialDirection( const DIRECTION_45& aDirection );
@@ -227,13 +194,13 @@ private:
     bool routeHead( const VECTOR2I& aP );
     bool tryWalkDp( NODE* aNode, DIFF_PAIR& aPair, bool aSolidsOnly );
 
-    ///> route step, walkaround mode
+    ///< route step, walk around mode
     bool rhWalkOnly( const VECTOR2I& aP );
 
-    ///> route step, shove mode
+    ///< route step, shove mode
     bool rhShoveOnly ( const VECTOR2I& aP );
 
-    ///> route step, mark obstacles mode
+    ///< route step, mark obstacles mode
     bool rhMarkObstacles( const VECTOR2I& aP );
 
     const VIA makeVia ( const VECTOR2I& aP, int aNet );
@@ -260,36 +227,36 @@ private:
     DP_PRIMITIVE_PAIR m_start;
     OPT<DP_PRIMITIVE_PAIR> m_prevPair;
 
-    ///> current algorithm iteration
+    ///< current algorithm iteration
     int m_iteration;
 
-    ///> pointer to world to search colliding items
+    ///< pointer to world to search colliding items
     NODE* m_world;
 
-    ///> current routing start point (end of tail, beginning of head)
+    ///< current routing start point (end of tail, beginning of head)
     VECTOR2I m_p_start;
 
-    ///> The shove engine
+    ///< The shove engine
     SHOVE* m_shove;
 
-    ///> Current world state
+    ///< Current world state
     NODE* m_currentNode;
 
-    ///> Postprocessed world state (including marked collisions & removed loops)
+    ///< Postprocessed world state (including marked collisions & removed loops)
     NODE* m_lastNode;
 
     SIZES_SETTINGS m_sizes;
 
-    ///> Are we placing a via?
+    ///< Are we placing a via?
     bool m_placingVia;
 
-    ///> current via diameter
+    ///< current via diameter
     int m_viaDiameter;
 
-    ///> current via drill
+    ///< current via drill
     int m_viaDrill;
 
-    ///> current track width
+    ///< current track width
     int m_currentWidth;
 
     int m_currentNet;

pcbnew/router/pns_dp_meander_placer.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -41,8 +42,6 @@ namespace PNS {
 class ROUTER;
 
 /**
- * DP_MEANDER_PLACER
- *
  * Differential Pair length-matching/meandering tool.
  */
 
@@ -53,30 +52,24 @@ public:
     ~DP_MEANDER_PLACER();
 
     /**
-     * Function Start()
+     * Start routing a single track at point \a aP, taking item \a aStartItem as anchor
-     *
-     * Starts routing a single track at point aP, taking item aStartItem as anchor
      * (unless NULL).
      */
     bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override;
 
     /**
-     * Function Move()
+     * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as
-     *
+     * anchor (if not NULL).
-     * Moves the end of the currently routed trace to the point aP, taking
-     * aEndItem as anchor (if not NULL).
-     * (unless NULL).
      */
     bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override;
 
     /**
-     * Function FixRoute()
+     * Commit the currently routed track to the parent node, taking \a aP as the final end
+     * point and \a aEndItem as the final anchor (if provided).
      *
-     * Commits the currently routed track to the parent node, taking
+     * @return true if route has been committed.  May return false if the routing result is
-     * aP as the final end point and aEndItem as the final anchor (if provided).
+     *         violating design rules.  In such cases, the track is only committed if
-     * @return true, if route has been commited. May return false if the routing
+     *         Settings.CanViolateDRC() is on.
-     * result is violating design rules - in such case, the track is only committed
-     * if Settings.CanViolateDRC() is on.
      */
     bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish = false ) override;
 
@@ -92,9 +85,7 @@ public:
     const LINE Trace() const;
 
     /**
-     * Function CurrentNode()
+     * Return the most recent world state.
-     *
-     * Returns the most recent world state.
      */
     NODE* CurrentNode( bool aLoopsRemoved = false ) const override;
 
@@ -131,10 +122,10 @@ private:
 
     long long int origPathLength() const;
 
-    ///> current routing start point (end of tail, beginning of head)
+    ///< Current routing start point (end of tail, beginning of head).
     VECTOR2I m_currentStart;
 
-    ///> Current world state
+    ///< Current world state.
     NODE* m_currentNode;
 
     DIFF_PAIR m_originPair;

pcbnew/router/pns_item.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2017 CERN
- * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -46,17 +47,17 @@ enum LineMarker {
 
 
 /**
- * ITEM
+ * Base class for PNS router board items.
  *
- * Base class for PNS router board items. Implements the shared properties of all PCB items -
+ * Implements the shared properties of all PCB items  net, spanned layers, geometric shape and
- * net, spanned layers, geometric shape & refererence to owning model.
+ * reference to owning model.
  */
 class ITEM
 {
 public:
     static const int UnusedNet = INT_MAX;
 
-    ///> Supported item types
+    ///< Supported item types
     enum PnsKind
     {
         SOLID_T     =    1,
@@ -97,17 +98,13 @@ public:
     virtual ~ITEM();
 
     /**
-     * Function Clone()
+     * Return a deep copy of the item.
-     *
-     * Returns a deep copy of the item
      */
     virtual ITEM* Clone() const = 0;
 
     /*
-     * Function Hull()
+     * Returns a convex polygon "hull" of a the item, that is used as the walk-around path.
      *
-     * Returns a convex polygon "hull" of a the item, that is used as the walk-around
-     * path.
      * @param aClearance defines how far from the body of the item the hull should be,
      * @param aWalkaroundThickness is the width of the line that walks around this hull.
      */
@@ -124,9 +121,7 @@ public:
     }
 
     /**
-     * Function Kind()
+     * Return the type (kind) of the item.
-     *
-     * Returns the type (kind) of the item
      */
     PnsKind Kind() const
     {
@@ -134,9 +129,7 @@ public:
     }
 
     /**
-     * Function OfKind()
+     * Return true if the item's type matches the mask \a aKindMask.
-     *
-     * Returns true if the item's type matches the mask aKindMask.
      */
     bool OfKind( int aKindMask ) const
     {
@@ -144,8 +137,6 @@ public:
     }
 
     /**
-     * Function KindStr()
-     *
      * Returns the kind of the item, as string
      */
     std::string KindStr() const;
@@ -163,10 +154,7 @@ public:
     virtual int Layer() const { return Layers().Start(); }
 
     /**
-     * Function LayersOverlap()
+     * Return true if the set of layers spanned by aOther overlaps our layers.
-     *
-     * Returns true if the set of layers spanned by aOther overlaps our
-     * layers.
      */
     bool LayersOverlap( const ITEM* aOther ) const
     {
@@ -174,22 +162,16 @@ public:
     }
 
     /**
-     * Function Owner()
+     * Return the owner of this item, or NULL if there's none.
-     *
-     * Returns the owner of this item, or NULL if there's none.
      */
     NODE* Owner() const { return m_owner; }
 
     /**
-     * Functon SetOwner()
+     * Set the node that owns this item. An item can belong to a single NODE or be unowned.
-     *
-     * Sets the node that owns this item. An item can belong to a single NODE or be unowned.
      */
     void SetOwner( NODE* aOwner ) { m_owner = aOwner; }
 
     /**
-     * Function BelongsTo()
-     *
      * @return true if the item is owned by the node aNode.
      */
     bool BelongsTo( NODE* aNode ) const
@@ -198,21 +180,18 @@ public:
     }
 
     /**
-     * Function Collide()
+     * Check for a collision (clearance violation) with between us and item \a aOther.
      *
-     * Checks for a collision (clearance violation) with between us and item aOther.
+     * Collision checking takes all PCB stuff into account (layers, nets, DRC rules).
-     * Collision checking takes all PCB stuff into accound (layers, nets, DRC rules).
      * Optionally returns a minimum translation vector for force propagation algorithm.
      *
-     * @param aOther item to check collision against
+     * @param aOther is the item to check collision against.
      * @return true, if a collision was found.
      */
     bool Collide( const ITEM* aOther, const NODE* aNode, bool aDifferentNetsOnly = true ) const;
 
     /**
-     * Function Shape()
+     * Return the geometrical shape of the item. Used for collision detection and spatial indexing.
-     *
-     * Returns the geometrical shape of the item. Used for collision detection & spatial indexing.
      */
     virtual const SHAPE* Shape() const
     {

pcbnew/router/pns_joint.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -33,20 +34,18 @@
 namespace PNS {
 
 /**
- * JOINT
+ * Represents a 2D point on a given set of layers and belonging to a certain net, that links
+ * together a number of board items.
  *
- * Represents a 2D point on a given set of layers and belonging to a certain
+ * A hash table of joints is used by the router to follow connectivity between the items.
- * net, that links together a number of board items.
- * A hash table of joints is used by the router to follow connectivity between
- * the items.
  **/
 class JOINT : public ITEM
 {
 public:
     typedef ITEM_SET::ENTRIES LINKED_ITEMS;
 
-    ///> Joints are hashed by their position, layers and net.
+    ///< Joints are hashed by their position, layers and net.
-    ///  Linked items are, obviously, not hashed
+    ///<  Linked items are, obviously, not hashed.
     struct HASH_TAG
     {
         VECTOR2I pos;
@@ -96,8 +95,8 @@ public:
         return NULL;
     }
 
-    ///> Returns true if the joint is a trivial line corner, connecting two
+    ///< Return true if the joint is a trivial line corner, connecting two
-    /// segments of the same net, on the same layer.
+    ///< segments of the same net, on the same layer.
     bool IsLineCorner() const
     {
         if( m_linkedItems.Size() != 2 || m_linkedItems.Count( SEGMENT_T | ARC_T ) != 2 )
@@ -138,7 +137,7 @@ public:
         return seg1->Width() != seg2->Width();
     }
 
-    ///> Links the joint to a given board item (when it's added to the NODE)
+    ///< Link the joint to a given board item (when it's added to the NODE).
     void Link( ITEM* aItem )
     {
         if( m_linkedItems.Contains( aItem ) )
@@ -147,16 +146,16 @@ public:
         m_linkedItems.Add( aItem );
     }
 
-    ///> Unlinks a given board item from the joint (upon its removal from a NODE)
+    ///< Unlink a given board item from the joint (upon its removal from a NODE)
-    ///> Returns true if the joint became dangling after unlinking.
+    ///< @return true if the joint became dangling after unlinking.
     bool Unlink( ITEM* aItem )
     {
         m_linkedItems.Erase( aItem );
         return m_linkedItems.Size() == 0;
     }
 
-    ///> For trivial joints, returns the segment adjacent to (aCurrent). For non-trival ones, returns
+    ///< For trivial joints, return the segment adjacent to (aCurrent). For non-trival ones,
-    ///> NULL, indicating the end of line.
+    ///< return NULL, indicating the end of line.
     LINKED_ITEM* NextSegment( ITEM* aCurrent ) const
     {
         if( !IsLineCorner() )
@@ -253,13 +252,13 @@ public:
     }
 
 private:
-    ///> hash tag for unordered_multimap
+    ///< hash tag for unordered_multimap
     HASH_TAG m_tag;
 
-    ///> list of items linked to this joint
+    ///< list of items linked to this joint
     ITEM_SET m_linkedItems;
 
-    ///> locked (non-movable) flag
+    ///< locked (non-movable) flag
     bool m_locked;
 };
 

pcbnew/router/pns_layerset.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -25,9 +26,7 @@
 #include <algorithm>
 
 /**
- * LAYER_RANGE
+ * Represent a contiguous set of PCB layers.
- *
- * Represents a contiguous set of PCB layers.
  */
 class LAYER_RANGE
 {
@@ -106,7 +105,7 @@ public:
             m_end = aOther.m_end;
     }
 
-    ///> Shortcut for comparisons/overlap tests
+    ///< Shortcut for comparisons/overlap tests
     static LAYER_RANGE All()
     {
         return LAYER_RANGE( 0, 256 ); // fixme: use layer IDs header

pcbnew/router/pns_line.h

@@ -2,7 +2,8 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2017 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
@@ -40,9 +41,9 @@ class LINKED_ITEM;
 class NODE;
 class VIA;
 
+#define PNS_HULL_MARGIN 10
+
 /**
- * LINE
- *
  * Represents a track on a PCB, connecting two non-trivial joints (that is,
  * vias, pads, junctions between multiple traces or two traces different widths
  * and combinations of these). PNS_LINEs are NOT stored in the model (NODE).
@@ -50,21 +51,16 @@ class VIA;
  * belongs to/starts/ends them.
  *
  * PNS_LINEs can be either loose (consisting of segments that do not belong to
- * any NODE) or owned (with segments taken from a NODE) - these are
+ * any NODE) or owned (with segments taken from a NODE) - these are returned by
- * returned by NODE::AssembleLine and friends.
+ * #NODE::AssembleLine and friends.
  *
  * A LINE may have a VIA attached at its end (i.e. the last point) - this is used by via
  * dragging/force propagation stuff.
  */
-
-#define PNS_HULL_MARGIN 10
-
 class LINE : public LINK_HOLDER
 {
 public:
-
     /**
-     * Constructor
      * Makes an empty line.
      */
     LINE() :
@@ -79,10 +75,8 @@ public:
     LINE( const LINE& aOther );
 
     /**
-     * Constructor
+     * Copy properties (net, layers, etc.) from a base line and replaces the shape by another.
-     * Copies properties (net, layers, etc.) from a base line and replaces the shape
+     */
-     * by another
-     **/
     LINE( const LINE& aBase, const SHAPE_LINE_CHAIN& aLine ) :
         LINK_HOLDER( aBase ),
         m_line( aLine ),
@@ -96,9 +90,7 @@ public:
     }
 
     /**
-     * Constructor
+     * Construct a LINE for a lone VIA (ie a stitching via).
-     * Constructs a LINE for a lone VIA (ie a stitching via).
-     * @param aVia
      */
     LINE( const VIA& aVia ) :
         LINK_HOLDER( LINE_T ),
@@ -130,17 +122,17 @@ public:
         return IsLinked() && LinkCount() == SegmentCount();
     }
 
-    ///> Assigns a shape to the line (a polyline/line chain)
+    ///< Assign a shape to the line (a polyline/line chain).
     void SetShape( const SHAPE_LINE_CHAIN& aLine )
     {
         m_line = aLine;
         m_line.SetWidth( m_width );
     }
 
-    ///> Returns the shape of the line
+    ///< Return the shape of the line.
     const SHAPE* Shape() const override { return &m_line; }
 
-    ///> Modifiable accessor to the underlying shape
+    ///< Modifiable accessor to the underlying shape.
     SHAPE_LINE_CHAIN& Line() { return m_line; }
     const SHAPE_LINE_CHAIN& CLine() const { return m_line; }
 
@@ -149,41 +141,43 @@ public:
     int ArcCount() const { return m_line.ArcCount(); }
     int ShapeCount() const { return m_line.ShapeCount(); }
 
-    ///> Returns the aIdx-th point of the line
+    ///< Return the \a aIdx-th point of the line.
     const VECTOR2I& CPoint( int aIdx ) const { return m_line.CPoint( aIdx ); }
     const SEG CSegment( int aIdx ) const { return m_line.CSegment( aIdx ); }
 
-    ///> Sets line width
+    ///< Set line width.
     void SetWidth( int aWidth )
     {
         m_width = aWidth;
         m_line.SetWidth( aWidth );
     }
 
-    ///> Returns line width
+    ///< Return line width.
     int Width() const { return m_width; }
 
-    ///> Returns true if the line is geometrically identical as line aOther
+    ///< Return true if the line is geometrically identical as line \a aOther.
     bool CompareGeometry( const LINE& aOther );
 
-    ///> Reverses the point/vertex order
+    ///< Reverse the point/vertex order
     void Reverse();
 
-    ///> Clips the line to the nearest obstacle, traversing from the line's start vertex (0).
+    ///< Clip the line to the nearest obstacle, traversing from the line's start vertex (0).
-    ///> Returns the clipped line.
+    ///< Returns the clipped line.
     const LINE ClipToNearestObstacle( NODE* aNode ) const;
 
-    ///> Clips the line to a given range of vertices.
+    ///< Clip the line to a given range of vertices.
     void ClipVertexRange ( int aStart, int aEnd );
 
-    ///> Returns the number of corners of angles specified by mask aAngles.
+    ///< Return the number of corners of angles specified by mask aAngles.
     int CountCorners( int aAngles ) const;
 
-    ///> Calculates a line thightly wrapping a convex hull of an obstacle object (aObstacle).
+    /**
-    ///> aPrePath = path from origin to the obstacle
+     * Calculate a line tightly wrapping a convex hull of an obstacle object (aObstacle).
-    ///> aWalkaroundPath = path around the obstacle
+     * @param aPrePath is the path from origin to the obstacle.
-    ///> aPostPath = past from obstacle till the end
+     * @param aWalkaroundPath is the path around the obstacle.
-    ///> aCW = whether to walk around in clockwise or counter-clockwise direction.
+     * @param aPostPath is the path from obstacle till the end.
+     * @param aCW determines whether to walk around in clockwise or counter-clockwise direction.
+     */
     bool Walkaround( SHAPE_LINE_CHAIN aObstacle, SHAPE_LINE_CHAIN& aPre, SHAPE_LINE_CHAIN& aWalk,
                      SHAPE_LINE_CHAIN& aPost, bool aCw ) const;
 
@@ -191,7 +185,7 @@ public:
 
     bool Is45Degree() const;
 
-    ///> Prints out all linked segments
+    ///< Print out all linked segments.
     void ShowLinks() const;
 
     bool EndsWithVia() const { return m_hasVia; }
@@ -246,16 +240,16 @@ private:
     VECTOR2I snapDraggedCorner( const SHAPE_LINE_CHAIN& aPath, const VECTOR2I& aP,
                                 int aIndex ) const;
 
-    SHAPE_LINE_CHAIN m_line;                ///> The actual shape of the line.
+    SHAPE_LINE_CHAIN m_line;                ///< The actual shape of the line.
-    int              m_width;               ///> Our width.
+    int              m_width;               ///< Our width.
 
 
-    int              m_snapThreshhold;      ///> Width to smooth out jagged segments.
+    int              m_snapThreshhold;      ///< Width to smooth out jagged segments.
 
-    bool             m_hasVia;              ///> Optional via at the end point.
+    bool             m_hasVia;              ///< Optional via at the end point.
     VIA              m_via;
 
-    ITEM*            m_blockingObstacle;    ///> For mark obstacle mode.
+    ITEM*            m_blockingObstacle;    ///< For mark obstacle mode.
 };
 
 }

pcbnew/router/pns_line_placer.h

@@ -3,7 +3,8 @@
  *
  * Copyright (C) 2013-2017 CERN
  * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -96,7 +97,7 @@ public:
     void FlipPosture();
 
     /**
-     * Disables the mouse-trail portion of the posture solver; leaving only the manual posture
+     * Disable the mouse-trail portion of the posture solver; leaving only the manual posture
      * switch and the previous-segment posture algorithm
      */
     void SetMouseDisabled( bool aDisabled = true ) { m_disableMouse = aDisabled; }
@@ -114,10 +115,9 @@ private:
 };
 
 /**
- * LINE_PLACER
+ * Single track placement algorithm.
  *
- * Single track placement algorithm. Interactively routes a track.
+ * Interactively routes a track and applies shove and walk around algorithms when needed.
- * Applies shove and walkaround algorithms when needed.
  */
 
 class LINE_PLACER : public PLACEMENT_ALGO
@@ -127,29 +127,23 @@ public:
     ~LINE_PLACER();
 
     /**
-     * Function Start()
+     * Start routing a single track at point aP, taking item aStartItem as anchor (unless NULL).
-     *
-     * Starts routing a single track at point aP, taking item aStartItem as anchor
-     * (unless NULL).
      */
     bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override;
 
     /**
-     * Function Move()
+     * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as
-     *
+     * anchor (if not NULL).
-     * Moves the end of the currently routed trace to the point aP, taking
-     * aEndItem as anchor (if not NULL).
-     * (unless NULL).
      */
     bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override;
 
     /**
-     * Function FixRoute()
+     * Commit the currently routed track to the parent node taking \a aP as the final end point
+     * and \a aEndItem as the final anchor (if provided).
      *
-     * Commits the currently routed track to the parent node, taking aP as the final end point
+     * @return true if route has been committed. May return false if the routing result is
-     * and aEndItem as the final anchor (if provided).
+     *         violating design rules.  In such cases, the track is only committed if
-     * @return true, if route has been commited. May return false if the routing result is
+     *         CanViolateDRC() is on.
-     * violating design rules - in such case, the track is only committed if CanViolateDRC() is on.
      */
     bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish ) override;
 
@@ -162,54 +156,40 @@ public:
     bool HasPlacedAnything() const override;
 
     /**
-     * Function ToggleVia()
+     * Enable/disable a via at the end of currently routed trace.
-     *
-     * Enables/disables a via at the end of currently routed trace.
      */
     bool ToggleVia( bool aEnabled ) override;
 
     /**
-     * Function SetLayer()
+     * Set the current routing layer.
-     *
-     * Sets the current routing layer.
      */
     bool SetLayer( int aLayer ) override;
 
     /**
-     * Function Head()
+     * Return the "head" of the line being placed, that is the volatile part that has not been
-     *
-     * Returns the "head" of the line being placed, that is the volatile part that has not been
      * "fixed" yet.
      */
     const LINE& Head() const { return m_head; }
 
     /**
-     * Function Tail()
+     * Return the "tail" of the line being placed, the part which has already wrapped around
-     *
-     * Returns the "tail" of the line being placed, the part which has already wrapped around
      * and shoved some obstacles.
      */
     const LINE& Tail() const { return m_tail; }
 
     /**
-     * Function Trace()
+     * Return the complete routed line.
-     *
-     * Returns the complete routed line.
      */
     const LINE Trace() const;
 
     /**
-     * Function Traces()
+     * Return the complete routed line, as a single-member ITEM_SET.
-     *
-     * Returns the complete routed line, as a single-member ITEM_SET.
      */
     const ITEM_SET Traces() override;
 
     /**
-     * Function CurrentEnd()
+     * Return the current end of the line being placed. It may not be equal to the cursor
-     *
+     * position due to collisions.
-     * Returns the current end of the line being placed. It may not be equal
-     * to the cursor position due to collisions.
      */
     const VECTOR2I& CurrentEnd() const override
     {
@@ -217,9 +197,7 @@ public:
     }
 
     /**
-     * Function CurrentNet()
+     * Return the net code of currently routed track.
-     *
-     * Returns the net code of currently routed track.
      */
     const std::vector<int> CurrentNets() const override
     {
@@ -227,9 +205,7 @@ public:
     }
 
     /**
-     * Function CurrentLayer()
+     * Return the layer of currently routed track.
-     *
-     * Returns the layer of currently routed track.
      */
     int CurrentLayer() const override
     {
@@ -237,23 +213,18 @@ public:
     }
 
     /**
-     * Function CurrentNode()
+     * Return the most recent world state.
-     *
-     * Returns the most recent world state.
      */
     NODE* CurrentNode( bool aLoopsRemoved = false ) const override;
 
     /**
-     * Function FlipPosture()
+     * Toggle the current posture (straight/diagonal) of the trace head.
-     *
-     * Toggles the current posture (straight/diagonal) of the trace head.
      */
     void FlipPosture() override;
 
     /**
-     * Function UpdateSizes()
+     * Perform on-the-fly update of the width, via diameter & drill size from a settings class.
      *
-     * Performs on-the-fly update of the width, via diameter & drill size from a settings class.
      * Used to dynamically change these parameters as the track is routed.
      */
     void UpdateSizes( const SIZES_SETTINGS& aSizes ) override;
@@ -265,145 +236,123 @@ public:
     void GetModifiedNets( std::vector<int>& aNets ) const override;
 
     /**
-     * Function SplitAdjacentSegments()
+     * Check if point \a aP lies on segment \a aSeg. If so, splits the segment in two, forming a
-     *
+     * joint at \a aP and stores updated topology in node \a aNode.
-     * Checks if point aP lies on segment aSeg. If so, splits the segment in two, forming a
-     * joint at aP and stores updated topology in node aNode.
      */
     bool SplitAdjacentSegments( NODE* aNode, ITEM* aSeg, const VECTOR2I& aP );
 
 
 private:
     /**
-     * Function route()
+     * Re-route the current track to point aP. Returns true, when routing has completed
-     *
+     * successfully (i.e. the trace end has reached point \a aP), and false if the trace was
-     * Re-routes the current track to point aP. Returns true, when routing has completed
-     * successfully (i.e. the trace end has reached point aP), and false if the trace was
      * stuck somewhere on the way. May call routeStep() repetitively due to mouse smoothing.
+     *
      * @param aP ending point of current route.
      * @return true, if the routing is complete.
      */
     bool route( const VECTOR2I& aP );
 
     /**
-     * Function updateLeadingRatLine()
+     * Draw the "leading" rats nest line, which connects the end of currently routed track and
-     *
-     * Draws the "leading" ratsnest line, which connects the end of currently routed track and
      * the nearest yet unrouted item. If the routing for current net is complete, draws nothing.
      */
     void updateLeadingRatLine();
 
     /**
-     * Function setWorld()
+     * Set the board to route.
-     *
-     * Sets the board to route.
      */
     void setWorld( NODE* aWorld );
 
     /**
-     * Function startPlacement()
+     * Initialize placement of a new line with given parameters.
-     *
-     * Initializes placement of a new line with given parameters.
      */
     void initPlacement();
 
     /**
-     * Function setInitialDirection()
+     * Set preferred direction of the very first track segment to be laid.
-     *
-     * Sets preferred direction of the very first track segment to be laid.
      * Used by posture switching mechanism.
      */
     void setInitialDirection( const DIRECTION_45& aDirection );
 
     /**
-     * Function removeLoops()
-     *
      * Searches aNode for traces concurrent to aLatest and removes them. Updated
      * topology is stored in aNode.
      */
     void removeLoops( NODE* aNode, LINE& aLatest );
 
     /**
-     * Assembles a line starting from segment or arc aLatest, removes collinear segments
+     * Assemble a line starting from segment or arc aLatest, removes collinear segments
-     * and redundant vertexes. If a simplification bhas been found, replaces the
+     * and redundant vertexes.  If a simplification has been found, replaces the old line
-     * old line with the simplified one in aNode.
+     * with the simplified one in \a aNode.
      */
     void simplifyNewLine( NODE* aNode, LINKED_ITEM* aLatest );
 
     /**
-     * Function handleSelfIntersections()
+     * Check if the head of the track intersects its tail. If so, cuts the tail up to the
+     * intersecting segment and fixes the head direction to match the last segment before
+     * the cut.
      *
-     * Checks if the head of the track intersects its tail. If so, cuts the
-     * tail up to the intersecting segment and fixes the head direction to match
-     * the last segment before the cut.
      * @return true if the line has been changed.
      */
     bool handleSelfIntersections();
 
     /**
-     * Function handlePullback()
+     * Deal with pull-back: reduces the tail if head trace is moved backwards wrs to the
+     * current tail direction.
      *
-     * Deals with pull-back: reduces the tail if head trace is moved backwards
-     * wrs to the current tail direction.
      * @return true if the line has been changed.
      */
     bool handlePullback();
 
     /**
-     * Function mergeHead()
+     * Moves "established" segments from the head to the tail if certain conditions are met.
      *
-     * Moves "estabished" segments from the head to the tail if certain
-     * conditions are met.
      * @return true, if the line has been changed.
      */
     bool mergeHead();
 
     /**
-     * Function reduceTail()
+     * Attempt to reduce the number of segments in the tail by trying to replace a certain
+     * number of latest tail segments with a direct trace leading to \a aEnd that does not
+     * collide with anything.
      *
-     * Attempts to reduce the numer of segments in the tail by trying to replace a
+     * @param aEnd is the current routing destination point.
-     * certain number of latest tail segments with a direct trace leading to aEnd
-     * that does not collide with anything.
-     * @param aEnd: current routing destination point.
      * @return true if the line has been changed.
      */
     bool reduceTail( const VECTOR2I& aEnd );
 
     /**
-     * Function optimizeTailHeadTransition()
+     * Try to reduce the corner count of the most recent part of tail/head by merging
+     * obtuse/collinear segments.
      *
-     * Tries to reduce the corner count of the most recent part of tail/head by
+     * @return true if the line has been changed.
-     * merging obtuse/collinear segments.
-     * @return true, if the line has been changed.
      */
     bool optimizeTailHeadTransition();
 
     /**
-     * Function routeHead()
+     * Compute the head trace between the current start point (m_p_start) and point \a aP,
-     *
+     * starting with direction defined in m_direction.  The trace walks around all
-     * Computes the head trace between the current start point (m_p_start) and
+     * colliding solid or non-movable items.  Movable segments are ignored, as they'll be
-     * point aP, starting with direction defined in m_direction. The trace walks
+     * handled later by the shove algorithm.
-     * around all colliding solid or non-movable items. Movable segments are
-     * ignored, as they'll be handled later by the shove algorithm.
      */
     bool routeHead( const VECTOR2I& aP, LINE& aNewHead );
 
     /**
-     * Function routeStep()
+     * Perform a single routing algorithm step, for the end point \a aP.
      *
-     * Performs a single routing alorithm step, for the end point aP.
+     * @param aP is the  ending point of current route.
-     * @param aP ending point of current route
+     * @return true if the line has been changed.
-     * @return true, if the line has been changed.
      */
     void routeStep( const VECTOR2I& aP );
 
-    ///> route step, walkaround mode
+    ///< Route step walk around mode.
     bool rhWalkOnly( const VECTOR2I& aP, LINE& aNewHead );
 
-    ///> route step, shove mode
+    ///< Route step shove mode.
     bool rhShoveOnly( const VECTOR2I& aP, LINE& aNewHead );
 
-    ///> route step, mark obstacles mode
+    ///< Route step mark obstacles mode.
     bool rhMarkObstacles( const VECTOR2I& aP, LINE& aNewHead );
 
     const VIA makeVia( const VECTOR2I& aP );
@@ -411,23 +360,23 @@ private:
     bool buildInitialLine( const VECTOR2I& aP, LINE& aHead );
 
 
-    DIRECTION_45   m_direction;         ///> current routing direction
+    DIRECTION_45   m_direction;         ///< current routing direction
-    DIRECTION_45   m_initial_direction; ///> routing direction for new traces
+    DIRECTION_45   m_initial_direction; ///< routing direction for new traces
 
-    LINE           m_head;          ///> the volatile part of the track from the previously
+    LINE           m_head;          ///< the volatile part of the track from the previously
-                                    ///> analyzed point to the current routing destination
+                                    ///< analyzed point to the current routing destination
 
-    LINE           m_tail;          ///> routing "tail": part of the track that has been already
+    LINE           m_tail;          ///< routing "tail": part of the track that has been already
-                                    ///> fixed due to collisions with obstacles
+                                    ///< fixed due to collisions with obstacles
 
-    NODE*          m_world;         ///> pointer to world to search colliding items
+    NODE*          m_world;         ///< pointer to world to search colliding items
-    VECTOR2I       m_p_start;       ///> current routing start (end of tail, beginning of head)
+    VECTOR2I       m_p_start;       ///< current routing start (end of tail, beginning of head)
 
-    std::unique_ptr<SHOVE> m_shove; ///> The shove engine
+    std::unique_ptr<SHOVE> m_shove; ///< The shove engine
 
-    NODE*          m_currentNode;   ///> Current world state
+    NODE*          m_currentNode;   ///< Current world state
-    NODE*          m_lastNode;      ///> Postprocessed world state (including marked collisions &
+    NODE*          m_lastNode;      ///< Postprocessed world state (including marked collisions &
-                                    ///> removed loops)
+                                    ///< removed loops)
 
     SIZES_SETTINGS m_sizes;
 

pcbnew/router/pns_link_holder.h

@@ -2,6 +2,8 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2019 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * Author: Seth Hillbrand <hillbrand@ucdavis.edu>
  * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.h>
  *
@@ -36,14 +38,14 @@ public:
     LINK_HOLDER( PnsKind aKind ) : ITEM( aKind )
     {}
 
-    ///> Adds a reference to an item registered in a NODE that is a part of this line.
+    ///< Add a reference to an item registered in a #NODE that is a part of this line.
     void Link( LINKED_ITEM* aLink )
     {
         m_links.push_back( aLink );
     }
 
-    ///> Returns the list of links from the owning node that constitute this
+    ///< Return the list of links from the owning node that constitute this
-    ///> line (or NULL if the line is not linked)
+    ///< line (or NULL if the line is not linked).
     LINKS& Links() { return m_links; }
     const LINKS& Links() const { return m_links; }
 
@@ -52,7 +54,7 @@ public:
         return m_links.size() != 0;
     }
 
-    ///> Checks if the segment aLink is a part of the line.
+    ///< Check if the segment aLink is a part of the line.
     bool ContainsLink( const LINKED_ITEM* aItem ) const
     {
         return alg::contains( m_links, aItem );
@@ -63,13 +65,13 @@ public:
         return m_links[aIndex];
     }
 
-    ///> Erases the linking information. Used to detach the line from the owning node.
+    ///< Erase the linking information. Used to detach the line from the owning node.
     virtual void ClearLinks()
     {
         m_links.clear();
     }
 
-    ///> Returns the number of segments that were assembled together to form this line.
+    ///< Return the number of segments that were assembled together to form this line.
     int LinkCount() const
     {
         return m_links.size();
@@ -77,7 +79,7 @@ public:
 
     void ShowLinks() const
     {
-        #if 0 // fixme: move outside header
+#if 0 /// @todo move outside header.
         if( !IsLinked() )
         {
             wxLogTrace( "PNS", "item %p: no links", this );
@@ -92,14 +94,14 @@ public:
     }
 
 protected:
-    ///> Copies m_links from the line aParent.
+    ///< Copy m_links from the line \a aParent.
     void copyLinks( const LINK_HOLDER* aParent )
     {
         m_links = aParent->m_links;
     }
 
-    ///> List of segments in the owning NODE (ITEM::m_owner) that constitute this line, or NULL
+    ///< List of segments in the owning NODE (ITEM::m_owner) that constitute this line, or NULL
-    ///> if the line is not a part of any node.
+    ///< if the line is not a part of any node.
     LINKS m_links;
 };
 

pcbnew/router/pns_meander.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2015 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -30,8 +31,9 @@
 namespace PNS {
 
 class MEANDER_PLACER_BASE;
+class MEANDERED_LINE;
 
-///< Shapes of available meanders
+///< Shapes of available meanders.
 enum MEANDER_TYPE {
         MT_SINGLE,          // _|^|_, single-sided
         MT_START,           // _|^|
@@ -43,16 +45,14 @@ enum MEANDER_TYPE {
         MT_EMPTY            // no meander (straight line)
 };
 
-///> meander corner shape
+///< Meander corner shape.
 enum MEANDER_STYLE {
     MEANDER_STYLE_ROUND = 1,          // rounded (90 degree arc)
     MEANDER_STYLE_CHAMFER             // chamfered (45 degree segment)
 };
 
 /**
- * MEANDER_SETTINGS
+ * Dimensions for the meandering algorithm.
- *
- * Holds dimensions for the meandering algorithm.
  */
 class MEANDER_SETTINGS
 {
@@ -73,47 +73,41 @@ public:
         m_cornerArcSegments = 8;
     }
 
-    ///> minimum meandering amplitude
+    ///< Minimum meandering amplitude.
     int m_minAmplitude;
-    ///> maximum meandering amplitude
+    ///< Maximum meandering amplitude.
     int m_maxAmplitude;
-    ///> meandering period/spacing (see dialog picture for explanation)
+    ///< Meandering period/spacing (see dialog picture for explanation).
     int m_spacing;
-    ///> amplitude/spacing adjustment step
+    ///< Amplitude/spacing adjustment step.
     int m_step;
-    ///> length PadToDie
+    ///< Length PadToDie.
     int m_lenPadToDie;
-    ///> desired length of the tuned line/diff pair (this is in nm, so allow more than board width)
+    ///< Desired length of the tuned line/diff pair (this is in nm, so allow more than board width).
     long long int m_targetLength;
-    ///> type of corners for the meandered line
+    ///< Type of corners for the meandered line.
     MEANDER_STYLE m_cornerStyle;
-    ///> rounding percentage (0 - 100)
+    ///< Rounding percentage (0 - 100).
     int m_cornerRadiusPercentage;
-    ///> allowable tuning error
+    ///< Allowable tuning error.
     int m_lengthTolerance;
-    ///> number of line segments for arc approximation
+    ///< Number of line segments for arc approximation.
     int m_cornerArcSegments;
-    ///> target skew value for diff pair de-skewing
+    ///< Target skew value for diff pair de-skewing.
     int m_targetSkew;
 };
 
-class MEANDERED_LINE;
-
 /**
- * MEANDER_SETTINGS
+ * The geometry of a single meander.
- *
- * Holds the geometry of a single meander.
  */
 class MEANDER_SHAPE
 {
 public:
     /**
-     * Constructor
+     * @param aPlacer the meander placer instance.
-     *
+     * @param aWidth width of the meandered line.
-     * @param aPlacer the meander placer instance
-     * @param aWidth width of the meandered line
      * @param aIsDual when true, the shape contains two meandered
-     *                lines at a given offset (diff pairs)
+     *                lines at a given offset (diff pairs).
      */
     MEANDER_SHAPE( MEANDER_PLACER_BASE* aPlacer, int aWidth, bool aIsDual = false ) :
         m_placer( aPlacer ),
@@ -121,7 +115,7 @@ public:
         m_width( aWidth ),
         m_baselineOffset( 0 )
     {
-        // Do not leave unitialized members, and keep static analyser quiet:
+        // Do not leave uninitialized members, and keep static analyzer quiet:
         m_type = MT_SINGLE;
         m_amplitude = 0;
         m_side = false;
@@ -131,9 +125,7 @@ public:
     }
 
     /**
-     * Function SetType()
+     * Set the type of the meander.
-     *
-     * Sets the type of the meander.
      */
     void SetType( MEANDER_TYPE aType )
     {
@@ -141,8 +133,6 @@ public:
     }
 
     /**
-     * Function Type()
-     *
      * @return the type of the meander.
      */
     MEANDER_TYPE Type() const
@@ -151,9 +141,7 @@ public:
     }
 
     /**
-     * Function SetBaseIndex()
+     * Set an auxiliary index of the segment being meandered in its original LINE.
-     *
-     * Sets an auxillary index of the segment being meandered in its original LINE.
      */
     void SetBaseIndex( int aIndex )
     {
@@ -161,9 +149,7 @@ public:
     }
 
     /**
-     * Function BaseIndex()
+     * @return auxiliary index of the segment being meandered in its original LINE.
-     *
-     * @return auxillary index of the segment being meandered in its original LINE.
      */
     int BaseIndex() const
     {
@@ -171,8 +157,6 @@ public:
     }
 
     /**
-     * Function Amplitude()
-     *
      * @return the amplitude of the meander shape.
      */
     int Amplitude() const
@@ -181,34 +165,28 @@ public:
     }
 
     /**
-     * Function MakeCorner()
+     * Create a dummy meander shape representing a line corner. Used to define
-     *
-     * Creates a dummy meander shape representing a line corner. Used to define
      * the starts/ends of meandered segments.
-     * @param aP1 corner point of the 1st line
+     *
-     * @param aP2 corner point of the 2nd line (if m_dual == true)
+     * @param aP1 corner point of the 1st line.
+     * @param aP2 corner point of the 2nd line (if m_dual == true).
      */
     void MakeCorner( VECTOR2I aP1, VECTOR2I aP2 = VECTOR2I( 0, 0 ) );
 
     /**
-     * Function Resize()
+     * Change the amplitude of the meander shape to aAmpl and recalculates the resulting
+     * line chain.
      *
-     * Changes the amplitude of the meander shape to aAmpl and recalculates
-     * the resulting line chain.
      * @param aAmpl new amplitude.
      */
     void Resize( int aAmpl );
 
     /**
-     * Function Recalculate()
+     * Recalculate the line chain representing the meander's shape.
-     *
-     * Recalculates the line chain representing the meanders's shape.
      */
     void Recalculate();
 
     /**
-     * Function IsDual()
-     *
      * @return true if the shape represents 2 parallel lines (diff pair).
      */
     bool IsDual() const
@@ -217,8 +195,6 @@ public:
     }
 
     /**
-     * Function Side()
-     *
      * @return true if the meander is to the right of its base segment.
      */
     bool Side() const
@@ -227,8 +203,6 @@ public:
     }
 
     /**
-     * Function End()
-     *
      * @return end vertex of the base segment of the meander shape.
      */
     VECTOR2I End() const
@@ -237,8 +211,6 @@ public:
     }
 
     /**
-     * Function CLine()
-     *
      * @return the line chain representing the shape of the meander.
      */
     const SHAPE_LINE_CHAIN& CLine( int aShape ) const
@@ -247,30 +219,25 @@ public:
     }
 
     /**
-     * Function MakeEmpty()
+     * Replace the meander with straight bypass line(s), effectively clearing it.
-     *
-     * Replaces the meander with straight bypass line(s), effectively
-     * clearing it.
      */
     void MakeEmpty();
 
     /**
-     * Function Fit()
+     * Attempt to fit a meander of a given type onto a segment, avoiding collisions with other
+     * board features.
      *
-     * Attempts to fit a meander of a given type onto a segment, avoiding
+     * @param aType type of meander shape.
-     * collisions with other board features.
+     * @param aSeg base segment for meandering.
-     * @param aType type of meander shape
+     * @param aP start point of the meander.
-     * @param aSeg base segment for meandering
+     * @param aSide side of aSeg to put the meander on (true = right).
-     * @param aP start point of the meander
-     * @param aSide side of aSeg to put the meander on (true = right)
      * @return true on success.
      */
     bool Fit( MEANDER_TYPE aType, const SEG& aSeg, const VECTOR2I& aP, bool aSide );
 
     /**
-     * Function BaseSegment()
+     * Return the base segment the meander was fitted to.
      *
-     * Returns the base segment the meadner was fitted to.
      * @return the base segment.
      */
     const SEG& BaseSegment() const
@@ -279,30 +246,21 @@ public:
     }
 
     /**
-     * Function BaselineLength()
+     * @return length of the base segment for the meander (i.e.the minimum tuned length).
-     *
-     * @return length of the base segment for the meander (i.e.
-     *         the minimum tuned length.
      */
     int BaselineLength() const;
 
     /**
-     * Function MaxTunableLength()
-     *
      * @return the length of the fitted line chain.
      */
     int MaxTunableLength() const;
 
     /**
-     * Function Settings()
-     *
      * @return the current meandering settings.
      */
     const MEANDER_SETTINGS& Settings() const;
 
     /**
-     * Function Width()
-     *
      * @return width of the meandered line.
      */
     int Width() const
@@ -311,11 +269,10 @@ public:
     }
 
     /**
-     * Function SetBaselineOffset()
+     * Set the parallel offset between the base segment and the meandered line. Used for
+     * dual meanders (diff pair) only.
      *
-     * Sets the parallel offset between the base segment and the meandered
+     * @param aOffset the offset.
-     * line. Used for dual menaders (diff pair) only.
-     * @param aOffset the offset
      */
     void SetBaselineOffset( int aOffset )
     {
@@ -325,82 +282,99 @@ public:
 private:
     friend class MEANDERED_LINE;
 
-    ///> starts turtle drawing
+    ///< Start turtle drawing
     void start( SHAPE_LINE_CHAIN* aTarget, const VECTOR2D& aWhere, const VECTOR2D& aDir );
-    ///> moves turtle forward by aLength
+
+    ///< Move turtle forward by \a aLength.
     void forward( int aLength );
-    ///> turns the turtle by aAngle
+
+    ///< Turn the turtle by \a aAngle
     void turn( int aAngle );
-    ///> tells the turtle to draw a mitered corner of given radius and turn direction
+
+    ///< Tell the turtle to draw a mitered corner of given radius and turn direction.
     void miter( int aRadius, bool aSide );
-    ///> tells the turtle to draw an U-like shape
+
+    ///< Tell the turtle to draw an U-like shape.
     void uShape( int aSides, int aCorner, int aTop );
 
-    ///> generates a 90-degree circular arc
+    ///< Generate a 90-degree circular arc.
     SHAPE_LINE_CHAIN makeMiterShape( VECTOR2D aP, VECTOR2D aDir, bool aSide );
 
-    ///> reflects a point onto other side of a given segment
+    ///< Reflect a point onto other side of a given segment.
     VECTOR2I reflect( VECTOR2I aP, const SEG& aLine );
 
-    ///> produces a meander shape of given type
+    ///< Produce a meander shape of given type.
-    SHAPE_LINE_CHAIN genMeanderShape( VECTOR2D aP, VECTOR2D aDir, bool aSide, MEANDER_TYPE aType, int aAmpl, int aBaselineOffset = 0 );
+    SHAPE_LINE_CHAIN genMeanderShape( VECTOR2D aP, VECTOR2D aDir, bool aSide, MEANDER_TYPE aType,
+                                      int aAmpl, int aBaselineOffset = 0 );
 
-    ///> recalculates the clipped baseline after the parameters of
+    ///< Recalculate the clipped baseline after the parameters of the meander have been changed.
-    ///> the meander have been changed.
     void updateBaseSegment();
 
-    ///> returns sanitized corner radius value
+    ///< Return sanitized corner radius value.
     int cornerRadius() const;
 
-    ///> returns sanitized spacing value
+    ///< Return sanitized spacing value.
     int spacing() const;
 
-    ///> the type
+    ///< The type of meander.
     MEANDER_TYPE m_type;
-    ///> the placer that placed this meander
+
+    ///< The placer that placed this meander.
     MEANDER_PLACER_BASE* m_placer;
-    ///> dual or single line
+
+    ///< Dual or single line.
     bool m_dual;
-    ///> width of the line
+
+    ///< Width of the line.
     int m_width;
-    ///> amplitude of the meander
+
+    ///< Amplitude of the meander.
     int m_amplitude;
-    ///> offset wrs the base segment (dual only)
+
+    ///< Offset wrs the base segment (dual only).
     int m_baselineOffset;
-    ///> average radius of meander corners (for correction of DP meanders)
+
+    ///< Average radius of meander corners (for correction of DP meanders).
     int m_meanCornerRadius;
-    ///> first point of the meandered line
+
+    ///< First point of the meandered line.
     VECTOR2I m_p0;
-    ///> base segment (unclipped)
+
+    ///< Base segment (unclipped).
     SEG m_baseSeg;
-    ///> base segment (clipped)
+
+    ///< Base segment (clipped).
     SEG m_clippedBaseSeg;
-    ///> side (true = right)
+
+    ///< Side (true = right).
     bool m_side;
-    ///> the actual shapes (0 used for single, both for dual)
+
+    ///< The actual shapes (0 used for single, both for dual).
     SHAPE_LINE_CHAIN m_shapes[2];
-    ///> index of the meandered segment in the base line
+
+    ///< Index of the meandered segment in the base line.
     int m_baseIndex;
-    ///> current turtle direction
+
+    ///< The current turtle direction.
     VECTOR2D m_currentDir;
-    ///> current turtle position
+
+    ///< The current turtle position.
     VECTOR2D m_currentPos;
-    ///> the line the turtle is drawing on
+
+    ///< The line the turtle is drawing on.
     SHAPE_LINE_CHAIN* m_currentTarget;
 };
 
 
 /**
- * MEANDERED_LINE
+ * Represent a set of meanders fitted over a single or two lines.
- *
- * Represents a set of meanders fitted over a single or two lines.
  */
 class MEANDERED_LINE
 {
 public:
     MEANDERED_LINE()
     {
-        // Do not leave unitialized members, and keep static analyser quiet:
+        // Do not leave uninitialized members, and keep static analyzer quiet:
         m_placer = NULL;
         m_dual = false;
         m_width = 0;
@@ -408,8 +382,6 @@ public:
     }
 
     /**
-     * Constructor
-     *
      * @param aPlacer the meander placer instance
      * @param aIsDual when true, the meanders are generated for two coupled lines
      */
@@ -417,7 +389,7 @@ public:
         m_placer( aPlacer ),
         m_dual( aIsDual )
     {
-        // Do not leave unitialized members, and keep static analyser quiet:
+        // Do not leave uninitialized members, and keep static analyzer quiet:
         m_width = 0;
         m_baselineOffset = 0;
     }
@@ -428,34 +400,28 @@ public:
     }
 
     /**
-     * Function AddCorner()
+     * Create a dummy meander shape representing a line corner.  Used to define the starts/ends
+     * of meandered segments.
      *
-     * Creates a dummy meander shape representing a line corner. Used to define
+     * @param aA corner point of the 1st line.
-     * the starts/ends of meandered segments.
+     * @param aB corner point of the 2nd line (if m_dual == true).
-     * @param aA corner point of the 1st line
-     * @param aB corner point of the 2nd line (if m_dual == true)
      */
     void AddCorner( const VECTOR2I& aA, const VECTOR2I& aB = VECTOR2I( 0, 0 ) );
 
     /**
-     * Function AddMeander()
+     * Add a new meander shape the the meandered line.
      *
-     * Adds a new meander shape the the meandered line.
      * @param aShape the meander shape to add
      */
     void AddMeander( MEANDER_SHAPE* aShape );
 
     /**
-     * Function Clear()
+     * Clear the line geometry, removing all corners and meanders.
-     *
-     * Clears the line geometry, removing all corners and meanders.
      */
     void Clear();
 
     /**
-     * Function SetWidth()
+     * Set the line width.
-     *
-     * Sets the line width.
      */
     void SetWidth( int aWidth )
     {
@@ -463,12 +429,10 @@ public:
     }
 
     /**
-     * Function MeanderSegment()
+     * Fit maximum amplitude meanders on a given segment and adds to the current line.
      *
-     * Fits maximum amplitude meanders on a given segment and adds to the
+     * @param aSeg the base segment to meander.
-     * current line.
+     * @param aBaseIndex index of the base segment in the original line.
-     * @param aSeg the base segment to meander
-     * @param aBaseIndex index of the base segment in the original line
      */
     void MeanderSegment( const SEG& aSeg, int aBaseIndex = 0 );
 
@@ -479,9 +443,7 @@ public:
     }
 
     /**
-     * Function Meanders()
+     * @return set of meander shapes for this line.
-     *
-     * @return set of meander shapes for this line
      */
     std::vector<MEANDER_SHAPE*>& Meanders()
     {
@@ -489,19 +451,15 @@ public:
     }
 
     /**
-     * Function CheckSelfIntersections()
+     * Check if the given shape is intersecting with any other meander in the current line.
      *
-     * Checks if the given shape is intersecting with any other meander in
+     * @param aShape the shape to check.
-     * the current line.
+     * @param aClearance clearance value.
-     * @param aShape the shape to check
+     * @return true, if the meander shape is not colliding.
-     * @param aClearance clearance value
-     * @return true, if the meander shape is not colliding
      */
     bool CheckSelfIntersections( MEANDER_SHAPE* aShape, int aClearance );
 
     /**
-     * Function Settings()
-     *
      * @return the current meandering settings.
      */
     const MEANDER_SETTINGS& Settings() const;

pcbnew/router/pns_meander_placer.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -41,8 +42,6 @@ class SHOVE;
 class OPTIMIZER;
 
 /**
- * MEANDER_PLACER
- *
  * Single track length matching/meandering tool.
  */
 class MEANDER_PLACER : public MEANDER_PLACER_BASE
@@ -104,10 +103,10 @@ protected:
 
     virtual long long int origPathLength() const;
 
-    ///> current routing start point (end of tail, beginning of head)
+    ///< current routing start point (end of tail, beginning of head)
     VECTOR2I m_currentStart;
 
-    ///> Current world state
+    ///< Current world state
     NODE* m_currentNode;
 
     LINE     m_originLine;

pcbnew/router/pns_meander_placer_base.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2015 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -40,15 +41,13 @@ class SHOVE;
 class OPTIMIZER;
 
 /**
- * MEANDER_PLACER_BASE
+ * Base class for Single trace & Differential pair meandering tools, as both of them share a
- *
+ * lot of code.
- * Base class for Single trace & Differenial pair meandering tools, as
- * both of them share a lot of code.
  */
 class MEANDER_PLACER_BASE : public PLACEMENT_ALGO
 {
 public:
-    ///> Result of the length tuning operation
+    ///< Result of the length tuning operation
     enum TUNING_STATUS {
         TOO_SHORT = 0,
         TOO_LONG,
@@ -59,61 +58,49 @@ public:
     virtual ~MEANDER_PLACER_BASE();
 
     /**
-     * Function TuningInfo()
+     * Return a string describing the status and length of the tuned traces.
-     *
-     * Returns a string describing the status and length of the
-     * tuned traces.
      */
     virtual const wxString TuningInfo( EDA_UNITS aUnits ) const = 0;
 
     /**
-     * Function TuningStatus()
+     * Return the tuning status (too short, too long, etc.) of the trace(s) being tuned.
-     *
-     * Returns the tuning status (too short, too long, etc.)
-     * of the trace(s) being tuned.
      */
     virtual TUNING_STATUS TuningStatus() const = 0;
 
     /**
-     * Function AmplitudeStep()
+     * Increase/decreases the current meandering amplitude by one step.
      *
-     * Increases/decreases the current meandering amplitude by one step.
      * @param aSign direction (negative = decrease, positive = increase).
      */
     virtual void AmplitudeStep( int aSign );
 
     /**
-     * Function SpacingStep()
+     * Increase/decrease the current meandering spacing by one step.
      *
-     * Increases/decreases the current meandering spcing by one step.
      * @param aSign direction (negative = decrease, positive = increase).
      */
     virtual void SpacingStep( int aSign );
 
     /**
-     * Function MeanderSettings()
+     * Return the current meandering configuration.
      *
-     * Returns the current meandering configuration.
      * @return the settings
      */
     virtual const MEANDER_SETTINGS& MeanderSettings() const;
 
     /*
-     * Function UpdateSettings()
+     * Set the current meandering configuration.
      *
-     * Sets the current meandering configuration.
+     * @param aSettings the settings.
-     * @param aSettings the settings
      */
     virtual void UpdateSettings( const MEANDER_SETTINGS& aSettings);
 
     /**
-     * Function CheckFit()
+     * Checks if it's OK to place the shape aShape (i.e. if it doesn't cause DRC violations
+     * or collide with other meanders).
      *
-     * Checks if it's ok to place the shape aShape (i.e.
+     * @param aShape the shape to check.
-     * if it doesn't cause DRC violations or collide with
+     * @return true if the shape fits.
-     * other meanders).
-     * @param aShape the shape to check
-     * @return true if the shape fits
      */
     virtual bool CheckFit( MEANDER_SHAPE* aShape )
     {
@@ -123,55 +110,48 @@ public:
     int GetTotalPadToDieLength( const LINE& aLine ) const;
 
 protected:
-
     /**
-     * Function cutTunedLine()
+     * Extract the part of a track to be meandered, depending on the starting point and the
+     * cursor position.
      *
-     * Extracts the part of a track to be meandered, depending on the
+     * @param aOrigin the original line.
-     * starting point and the cursor position.
+     * @param aTuneStart point where we start meandering (start click coordinates).
-     * @param aOrigin the original line
+     * @param aCursorPos current cursor position.
-     * @param aTuneStart point where we start meandering (start click coorinates)
+     * @param aPre part before the beginning of meanders.
-     * @param aCursorPos current cursor position
+     * @param aTuned part to be meandered.
-     * @param aPre part before the beginning of meanders
+     * @param aPost part after the end of meanders.
-     * @param aTuned part to be meandered
-     * @param aPost part after the end of meanders
      */
-    void cutTunedLine(  const SHAPE_LINE_CHAIN& aOrigin,
+    void cutTunedLine( const SHAPE_LINE_CHAIN& aOrigin, const VECTOR2I& aTuneStart,
-                        const VECTOR2I&         aTuneStart,
+                       const VECTOR2I& aCursorPos, SHAPE_LINE_CHAIN& aPre, SHAPE_LINE_CHAIN& aTuned,
-                        const VECTOR2I&         aCursorPos,
-                        SHAPE_LINE_CHAIN&       aPre,
-                        SHAPE_LINE_CHAIN&       aTuned,
                        SHAPE_LINE_CHAIN& aPost );
 
     /**
-     * Function tuneLineLength()
+     * Take a set of meanders in \a aTuned and tunes their length to extend the original line
-     *
+     * length by \a aElongation.
-     * Takes a set of meanders in aTuned and tunes their length to
-     * extend the original line length by aElongation.
      */
     void tuneLineLength( MEANDERED_LINE& aTuned, long long int aElongation );
 
     /**
-     * Function compareWithTolerance()
+     * Compare \a aValue against \a aExpected with given tolerance.
-     *
-     * Compares aValue against aExpected with given tolerance.
      */
-    int compareWithTolerance(
+    int compareWithTolerance( long long int aValue, long long int aExpected,
-            long long int aValue, long long int aExpected, long long int aTolerance = 0 ) const;
+                              long long int aTolerance = 0 ) const;
 
     VECTOR2I getSnappedStartPoint( LINKED_ITEM* aStartItem, VECTOR2I aStartPoint );
 
-    ///> pointer to world to search colliding items
+    ///< Pointer to world to search colliding items.
     NODE* m_world;
 
-    ///> total length added by pad to die size
+    ///< Total length added by pad to die size.
     int m_padToDieLenth;
 
-    ///> width of the meandered trace(s)
+    ///< Width of the meandered trace(s).
     int m_currentWidth;
-    ///> meandering settings
+
+    ///< Meander settings.
     MEANDER_SETTINGS m_settings;
-    ///> current end point
+
+    ///< The current end point.
     VECTOR2I m_currentEnd;
 };
 

pcbnew/router/pns_node.cpp

@@ -3,7 +3,8 @@
  *
  * Copyright (C) 2013-2019 CERN
  * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -132,7 +133,7 @@ NODE* NODE::Branch()
     child->m_root = isRoot() ? this : m_root;
     child->m_maxClearance = m_maxClearance;
 
-    // Immmediate offspring of the root branch needs not copy anything. For the rest, deep-copy
+    // Immediate offspring of the root branch needs not copy anything. For the rest, deep-copy
     // joints, overridden item maps and pointers to stored items.
     if( !isRoot() )
     {
@@ -183,7 +184,7 @@ void OBSTACLE_VISITOR::SetWorld( const NODE* aNode, const NODE* aOverride )
 
 bool OBSTACLE_VISITOR::visit( ITEM* aCandidate )
 {
-    // check if there is a more recent branch with a newer (possibily modified) version of this
+    // check if there is a more recent branch with a newer (possibly modified) version of this
     // item.
     if( m_override && m_override->Overrides( aCandidate ) )
         return true;
@@ -197,7 +198,7 @@ struct NODE::DEFAULT_OBSTACLE_VISITOR : public OBSTACLE_VISITOR
 {
     OBSTACLES& m_tab;
 
-    int        m_kindMask;          ///>  (solids, vias, segments, etc...)
+    int        m_kindMask;          ///<  (solids, vias, segments, etc...)
     int        m_limitCount;
     int        m_matchCount;
     int        m_extraClearance;
@@ -714,6 +715,7 @@ void NODE::rebuildJoint( JOINT* aJoint, ITEM* aItem )
     tag.pos = aJoint->Pos();
 
     bool split;
+
     do
     {
         split = false;
@@ -844,7 +846,7 @@ void NODE::Remove( ITEM* aItem )
 
 void NODE::Remove( LINE& aLine )
 {
-    // LINE does not have a seperate remover, as LINEs are never truly a member of the tree
+    // LINE does not have a separate remover, as LINEs are never truly a member of the tree
     std::vector<LINKED_ITEM*>& segRefs = aLine.Links();
 
     for( LINKED_ITEM* li : segRefs )
@@ -1162,6 +1164,7 @@ void NODE::Dump( bool aLong )
     JOINT_MAP::iterator j;
 
     if( aLong )
+    {
         for( j = m_joints.begin(); j != m_joints.end(); ++j )
         {
             wxLogTrace( "PNS", "joint : %s, links : %d\n",
@@ -1187,7 +1190,7 @@ void NODE::Dump( bool aLong )
                 }
             }
         }
-
+    }
 
     int lines_count = 0;
 

pcbnew/router/pns_node.h

@@ -3,7 +3,8 @@
  *
  * Copyright (C) 2013-2014 CERN
  * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -50,11 +51,9 @@ class ROUTER;
 class NODE;
 
 /**
- * RULE_RESOLVER
- *
  * An abstract function object, returning a design rule (clearance, diff pair gap, etc) required
  * between two items.
- **/
+ */
 
 enum class CONSTRAINT_TYPE
 {
@@ -102,23 +101,18 @@ public:
 };
 
 /**
- * Struct OBSTACLE
+ * Hold an object colliding with another object, along with some useful data about the collision.
- *
+ */
- * Holds an object colliding with another object, along with some useful data about the collision.
- **/
 struct OBSTACLE
 {
-    const ITEM*      m_head;        ///> Item we search collisions with
+    const ITEM*      m_head;        ///< Item we search collisions with
 
-    ITEM*            m_item;        ///> Item found to be colliding with m_head
+    ITEM*            m_item;        ///< Item found to be colliding with m_head
-    SHAPE_LINE_CHAIN m_hull;        ///> Hull of the colliding m_item
+    SHAPE_LINE_CHAIN m_hull;        ///< Hull of the colliding m_item
-    VECTOR2I         m_ipFirst;     ///> First intersection between m_head and m_hull
+    VECTOR2I         m_ipFirst;     ///< First intersection between m_head and m_hull
-    int              m_distFirst;   ///> ... and the distance thereof
+    int              m_distFirst;   ///< ... and the distance thereof
 };
 
-/**
- * Struct OBSTACLE_VISITOR
- **/
 class OBSTACLE_VISITOR
 {
 public:
@@ -136,23 +130,21 @@ protected:
     bool visit( ITEM* aCandidate );
 
 protected:
-    const ITEM* m_item;             ///> the item we are looking for collisions with
+    const ITEM* m_item;             ///< the item we are looking for collisions with
 
-    const NODE* m_node;             ///> node we are searching in (either root or a branch)
+    const NODE* m_node;             ///< node we are searching in (either root or a branch)
-    const NODE* m_override;         ///> node that overrides root entries
+    const NODE* m_override;         ///< node that overrides root entries
-    int         m_extraClearance;   ///> additional clearance
+    int         m_extraClearance;   ///< additional clearance
 };
 
 /**
- * NODE
+ * Keep the router "world" - i.e. all the tracks, vias, solids in a hierarchical and indexed way.
  *
- * Keeps the router "world" - i.e. all the tracks, vias, solids in a hierarchical and indexed way.
  * Features:
- * - spatial-indexed container for PCB item shapes
+ * - spatial-indexed container for PCB item shapes.
- * - collision search & clearance checking
+ * - collision search & clearance checking.
- * - assembly of lines connecting joints, finding loops and unique paths
+ * - assembly of lines connecting joints, finding loops and unique paths.
- * - lightweight cloning/branching (for recursive optimization and shove
+ * - lightweight cloning/branching (for recursive optimization and shove springback).
- * springback)
  **/
 class NODE
 {
@@ -164,24 +156,24 @@ public:
     NODE();
     ~NODE();
 
-    ///> Returns the expected clearance between items a and b.
+    ///< Return the expected clearance between items a and b.
     int GetClearance( const ITEM* aA, const ITEM* aB ) const;
     int GetHoleClearance( const ITEM* aA, const ITEM* aB ) const;
     int GetHoleToHoleClearance( const ITEM* aA, const ITEM* aB ) const;
 
-    ///> Returns the pre-set worst case clearance between any pair of items
+    ///< Return the pre-set worst case clearance between any pair of items.
     int GetMaxClearance() const
     {
         return m_maxClearance;
     }
 
-    ///> Sets the worst-case clerance between any pair of items
+    ///< Set the worst-case clearance between any pair of items.
     void SetMaxClearance( int aClearance )
     {
         m_maxClearance = aClearance;
     }
 
-    ///> Assigns a clerance resolution function object
+    ///< Assign a clearance resolution function object.
     void SetRuleResolver( RULE_RESOLVER* aFunc )
     {
         m_ruleResolver = aFunc;
@@ -192,93 +184,79 @@ public:
         return m_ruleResolver;
     }
 
-    ///> Returns the number of joints
+    ///< Return the number of joints.
     int JointCount() const
     {
         return m_joints.size();
     }
 
-    ///> Returns the number of nodes in the inheritance chain (wrs to the root node)
+    ///< Return the number of nodes in the inheritance chain (wrs to the root node).
     int Depth() const
     {
         return m_depth;
     }
 
     /**
-     * Function QueryColliding()
+     * Find items colliding (closer than clearance) with the item \a aItem.
      *
-     * Finds items collliding (closer than clearance) with the item aItem.
      * @param aItem item to check collisions against
      * @param aObstacles set of colliding objects found
      * @param aKindMask mask of obstacle types to take into account
      * @param aLimitCount stop looking for collisions after finding this number of colliding items
      * @return number of obstacles found
      */
-    int QueryColliding( const ITEM*  aItem,
+    int QueryColliding( const ITEM* aItem, OBSTACLES& aObstacles, int aKindMask = ITEM::ANY_T,
-                        OBSTACLES&   aObstacles,
+                        int aLimitCount = -1, bool aDifferentNetsOnly = true );
-                        int          aKindMask = ITEM::ANY_T,
-                        int          aLimitCount = -1,
-                        bool         aDifferentNetsOnly = true );
 
-    int QueryJoints( const BOX2I&         aBox,
+    int QueryJoints( const BOX2I& aBox, std::vector<JOINT*>& aJoints,
-                     std::vector<JOINT*>& aJoints,
+                     LAYER_RANGE aLayerMask = LAYER_RANGE::All(), int aKindMask = ITEM::ANY_T );
-                     LAYER_RANGE          aLayerMask = LAYER_RANGE::All(),
-                     int                  aKindMask = ITEM::ANY_T );
 
     /**
-     * Function NearestObstacle()
+     * Follow the line in search of an obstacle that is nearest to the starting to the line's
-     *
-     * Follows the line in search of an obstacle that is nearest to the starting to the line's
      * starting point.
+     *
      * @param aLine the item to find collisions with
      * @param aKindMask mask of obstacle types to take into account
      * @return the obstacle, if found, otherwise empty.
      */
-    OPT_OBSTACLE NearestObstacle( const LINE*             aLine,
+    OPT_OBSTACLE NearestObstacle( const LINE* aLine, int aKindMask = ITEM::ANY_T,
-                                  int                     aKindMask = ITEM::ANY_T,
                                   const std::set<ITEM*>* aRestrictedSet = NULL );
 
     /**
-     * Function CheckColliding()
+     * Check if the item collides with anything else in the world, and if found, returns the
-     *
-     * Checks if the item collides with anything else in the world, and if found, returns the
      * obstacle.
+     *
      * @param aItem the item to find collisions with
      * @param aKindMask mask of obstacle types to take into account
      * @return the obstacle, if found, otherwise empty.
      */
-    OPT_OBSTACLE CheckColliding( const ITEM*     aItem,
+    OPT_OBSTACLE CheckColliding( const ITEM* aItem, int aKindMask = ITEM::ANY_T );
-                                 int             aKindMask = ITEM::ANY_T );
 
 
     /**
-     * Function CheckColliding()
+     * Check if any item in the set collides with anything else in the world, and if found,
-     *
-     * Checks if any item in the set collides with anything else in the world, and if found,
      * returns the obstacle.
-     * @param aSet set of items to find collisions with
+     *
-     * @param aKindMask mask of obstacle types to take into account
+     * @param aSet set of items to find collisions with.
+     * @param aKindMask mask of obstacle types to take into account.
      * @return the obstacle, if found, otherwise empty.
      */
-    OPT_OBSTACLE CheckColliding( const ITEM_SET&  aSet,
+    OPT_OBSTACLE CheckColliding( const ITEM_SET&  aSet, int aKindMask = ITEM::ANY_T );
-                                 int              aKindMask = ITEM::ANY_T );
 
     /**
-     * Function HitTest()
+     * Find all items that contain the point \a aPoint.
      *
-     * Finds all items that contain the point aPoint.
+     * @param aPoint the point.
-     * @param aPoint the point
+     * @return the items.
-     * @return the items
      */
     const ITEM_SET HitTest( const VECTOR2I& aPoint ) const;
 
     /**
-     * Function Add()
+     * Add an item to the current node.
      *
-     * Adds an item to the current node.
+     * @param aSegment item to add.
-     * @param aSegment item to add
      * @param aAllowRedundant if true, duplicate items are allowed (e.g. a segment or via
-     *                        at the same coordinates as an existing one)
+     *                        at the same coordinates as an existing one).
      * @return true if added
      */
     bool Add( std::unique_ptr< SEGMENT > aSegment, bool aAllowRedundant = false );
@@ -288,14 +266,8 @@ public:
 
     void Add( LINE& aLine, bool aAllowRedundant = false );
 
-private:
-    void Add( std::unique_ptr< ITEM > aItem, bool aAllowRedundant = false );
-
-public:
     /**
-     * Function Remove()
+     * Remove an item from this branch.
-     *
-     * Just as the name says, removes an item from this branch.
      */
     void Remove( ARC* aArc );
     void Remove( SOLID* aSolid );
@@ -303,19 +275,16 @@ public:
     void Remove( SEGMENT* aSegment );
     void Remove( ITEM* aItem );
 
-public:
     /**
-     * Function Remove()
+     * Removes a line from this branch.
      *
-     * Just as the name says, removes a line from this branch.
      * @param aLine item to remove
      */
     void Remove( LINE& aLine );
 
     /**
-     * Function Replace()
+     * Replace an item with another one.
      *
-     * Just as the name says, replaces an item with another one.
      * @param aOldItem item to be removed
      * @param aNewItem item add instead
      */
@@ -323,78 +292,73 @@ public:
     void Replace( LINE& aOldLine, LINE& aNewLine );
 
     /**
-     * Function Branch()
+     * Create a lightweight copy (called branch) of self that tracks the changes (added/removed
+     * items) wrs to the root.
      *
-     * Creates a lightweight copy (called branch) of self that tracks the changes (added/removed
+     * @note If there are any branches in use, their parents must **not** be deleted.
-     * items) wrs to the root. Note that if there are any branches in use, their parents must NOT
+     *
-     * be deleted.
+     * @return the new branch.
-     * @return the new branch
      */
     NODE* Branch();
 
     /**
-     * Function AssembleLine()
+     * Follow the joint map to assemble a line connecting two non-trivial joints starting from
+     * segment \a aSeg.
      *
-     * Follows the joint map to assemble a line connecting two non-trivial joints starting from
+     * @param aSeg the initial segment.
-     * segment aSeg.
+     * @param aOriginSegmentIndex index of aSeg in the resulting line.
-     * @param aSeg the initial segment
-     * @param aOriginSegmentIndex index of aSeg in the resulting line
      * @return the line
      */
     const LINE AssembleLine( LINKED_ITEM* aSeg, int* aOriginSegmentIndex = NULL,
                              bool aStopAtLockedJoints = false );
 
-    ///> Prints the contents and joints structure
+    ///< Print the contents and joints structure.
     void Dump( bool aLong = false );
 
     /**
-     * Function GetUpdatedItems()
+     * Return the list of items removed and added in this branch with respect to the root branch.
      *
-     * Returns the list of items removed and added in this branch with respect to the root branch.
+     * @param aRemoved removed items.
-     * @param aRemoved removed items
+     * @param aAdded added items.
-     * @param aAdded added items
      */
     void GetUpdatedItems( ITEM_VECTOR& aRemoved, ITEM_VECTOR& aAdded );
 
     /**
-     * Function Commit()
+     * Apply the changes from a given branch (aNode) to the root branch.
      *
-     * Applies the changes from a given branch (aNode) to the root branch. Calling on a non-root
+     * Calling on a non-root branch will fail.  Calling commit also kills all children nodes of
-     * branch will fail. Calling commit also kills all children nodes of the root branch.
+     *  the root branch.
-     * @param aNode node to commit changes from
+     *
+     * @param aNode node to commit changes from.
      */
     void Commit( NODE* aNode );
 
     /**
-     * Function FindJoint()
+     * Search for a joint at a given position, layer and belonging to given net.
      *
-     * Searches for a joint at a given position, layer and belonging to given net.
+     * @return the joint, if found, otherwise empty.
-     * @return the joint, if found, otherwise empty
      */
     JOINT* FindJoint( const VECTOR2I& aPos, int aLayer, int aNet );
 
     void LockJoint( const VECTOR2I& aPos, const ITEM* aItem, bool aLock );
 
     /**
-     * Function FindJoint()
+     * Search for a joint at a given position, linked to given item.
      *
-     * Searches for a joint at a given position, linked to given item.
+     * @return the joint, if found, otherwise empty.
-     * @return the joint, if found, otherwise empty
      */
     JOINT* FindJoint( const VECTOR2I& aPos, const ITEM* aItem )
     {
         return FindJoint( aPos, aItem->Layers().Start(), aItem->Net() );
     }
 
-    ///> finds all lines between a pair of joints. Used by the loop removal procedure.
+    ///< Find all lines between a pair of joints. Used by the loop removal procedure.
-    int FindLinesBetweenJoints( const JOINT&            aA,
+    int FindLinesBetweenJoints( const JOINT& aA, const JOINT& aB, std::vector<LINE>& aLines );
-                                const JOINT&            aB,
-                                std::vector<LINE>&      aLines );
 
-    ///> finds the joints corresponding to the ends of line aLine
+    ///< Find the joints corresponding to the ends of line \a aLine.
     void FindLineEnds( const LINE& aLine, JOINT& aA, JOINT& aB );
 
-    ///> Destroys all child nodes. Applicable only to the root node.
+    ///< Destroy all child nodes. Applicable only to the root node.
     void KillChildren();
 
     void AllItemsInNet( int aNet, std::set<ITEM*>& aItems, int aKindMask = -1 );
@@ -415,33 +379,29 @@ public:
         return m_parent;
     }
 
-    ///> checks if this branch contains an updated version of the m_item from the root branch.
+    ///< Check if this branch contains an updated version of the m_item from the root branch.
     bool Overrides( ITEM* aItem ) const
     {
         return m_override.find( aItem ) != m_override.end();
     }
 
 private:
-    struct DEFAULT_OBSTACLE_VISITOR;
+    void Add( std::unique_ptr< ITEM > aItem, bool aAllowRedundant = false );
-    typedef std::unordered_multimap<JOINT::HASH_TAG, JOINT, JOINT::JOINT_TAG_HASH> JOINT_MAP;
-    typedef JOINT_MAP::value_type TagJointPair;
 
     /// nodes are not copyable
     NODE( const NODE& aB );
     NODE& operator=( const NODE& aB );
 
-    ///> tries to find matching joint and creates a new one if not found
+    ///< Try to find matching joint and creates a new one if not found.
-    JOINT& touchJoint( const VECTOR2I&     aPos,
+    JOINT& touchJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet );
-                       const LAYER_RANGE&  aLayers,
-                       int                 aNet );
 
-    ///> touches a joint and links it to an m_item
+    ///< Touch a joint and links it to an m_item.
     void linkJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet, ITEM* aWhere );
 
-    ///> unlinks an item from a joint
+    ///< Unlink an item from a joint.
     void unlinkJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet, ITEM* aWhere );
 
-    ///> helpers for adding/removing items
+    ///< Helpers for adding/removing items.
     void addSolid( SOLID* aSeg );
     void addSegment( SEGMENT* aSeg );
     void addVia( VIA* aVia );
@@ -470,27 +430,31 @@ private:
     ARC* findRedundantArc( const VECTOR2I& A, const VECTOR2I& B, const LAYER_RANGE& lr, int aNet );
     ARC* findRedundantArc( ARC* aSeg );
 
-    ///> scans the joint map, forming a line starting from segment (current).
+    ///< Scan the joint map, forming a line starting from segment (current).
     void followLine( LINKED_ITEM* aCurrent, int aScanDirection, int& aPos, int aLimit,
                      VECTOR2I* aCorners, LINKED_ITEM** aSegments, bool* aArcReversed,
                      bool& aGuardHit, bool aStopAtLockedJoints );
 
 private:
-    JOINT_MAP       m_joints;           ///> hash table with the joints, linking the items. Joints
+    struct DEFAULT_OBSTACLE_VISITOR;
-                                        ///> are hashed by their position, layer set and net.
+    typedef std::unordered_multimap<JOINT::HASH_TAG, JOINT, JOINT::JOINT_TAG_HASH> JOINT_MAP;
+    typedef JOINT_MAP::value_type TagJointPair;
 
-    NODE*           m_parent;           ///> node this node was branched from
+    JOINT_MAP       m_joints;           ///< hash table with the joints, linking the items. Joints
-    NODE*           m_root;             ///> root node of the whole hierarchy
+                                        ///< are hashed by their position, layer set and net.
-    std::set<NODE*> m_children;         ///> list of nodes branched from this one
 
-    std::unordered_set<ITEM*> m_override;   ///> hash of root's items that have been changed
+    NODE*           m_parent;           ///< node this node was branched from
-                                            ///> in this node
+    NODE*           m_root;             ///< root node of the whole hierarchy
+    std::set<NODE*> m_children;         ///< list of nodes branched from this one
 
-    int             m_maxClearance;     ///> worst case item-item clearance
+    std::unordered_set<ITEM*> m_override;   ///< hash of root's items that have been changed
-    RULE_RESOLVER*  m_ruleResolver;     ///> Design rules resolver
+                                            ///< in this node
-    INDEX*          m_index;            ///> Geometric/Net index of the items
+
-    int             m_depth;            ///> depth of the node (number of parent nodes in the
+    int             m_maxClearance;     ///< worst case item-item clearance
-                                        ///> inheritance chain)
+    RULE_RESOLVER*  m_ruleResolver;     ///< Design rules resolver
+    INDEX*          m_index;            ///< Geometric/Net index of the items
+    int             m_depth;            ///< depth of the node (number of parent nodes in the
+                                        ///< inheritance chain)
 
     std::unordered_set<ITEM*> m_garbageItems;
 };

pcbnew/router/pns_optimizer.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -39,12 +40,11 @@ class LINE;
 class DIFF_PAIR;
 class ITEM;
 class JOINT;
+class OPT_CONSTRAINT;
 
 /**
- * COST_ESTIMATOR
+ * Calculate the cost of a given line, taking corner angles and total length into account.
- *
+ */
- * Calculates the cost of a given line, taking corner angles and total length into account.
- **/
 class COST_ESTIMATOR
 {
 public:
@@ -79,19 +79,18 @@ private:
     int m_cornerCost;
 };
 
-class OPT_CONSTRAINT;
 
 /**
- * OPTIMIZER
+ * Perform various optimizations of the lines being routed, attempting to make the lines shorter
+ * and less cornery.
  *
- * Performs various optimizations of the lines being routed, attempting to make the lines shorter
+ * There are 3 kinds of optimizations so far:
- * and less cornery. There are 3 kinds of optimizations so far:
+ * - Merging obtuse segments (MERGE_OBTUSE): tries to join together as many  obtuse segments
- * - Merging obtuse segments (MERGE_OBTUSE): tries to join together as many
+ *   as possible without causing collisions.
- *   obtuse segments as possible without causing collisions
+ * - Rerouting path between pair of line corners with a 2-segment "\__" line and iteratively
- * - Rerouting path between pair of line corners with a 2-segment "\__" line and iteratively repeating
+ *   repeating the procedure as long as the total cost of the line keeps decreasing.
- *   the procedure as long as the total cost of the line keeps decreasing
  * - "Smart Pads" - that is, rerouting pad/via exits to make them look nice (SMART_PADS).
- **/
+ */
 class OPTIMIZER
 {
 public:
@@ -110,7 +109,7 @@ public:
     OPTIMIZER( NODE* aWorld );
     ~OPTIMIZER();
 
-    ///> a quick shortcut to optmize a line without creating and setting up an optimizer
+    ///< A quick shortcut to optimize a line without creating and setting up an optimizer.
     static bool Optimize( LINE* aLine, int aEffortLevel, NODE* aWorld,
                           const VECTOR2I aV = VECTOR2I(0, 0) );
 
@@ -208,6 +207,7 @@ private:
     BOX2I               m_restrictArea;
 };
 
+
 class OPT_CONSTRAINT
 {
 public:

pcbnew/router/pns_routing_settings.h

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2014 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -33,16 +34,16 @@ class TOOL_SETTINGS;
 
 namespace PNS {
 
-///> Routing modes
+///< Routing modes
 enum PNS_MODE
 {
-    RM_MarkObstacles = 0,   ///> Ignore collisions, mark obstacles
+    RM_MarkObstacles = 0,   ///< Ignore collisions, mark obstacles
-    RM_Shove,               ///> Only shove
+    RM_Shove,               ///< Only shove
-    RM_Walkaround,          ///> Only walkaround
+    RM_Walkaround,          ///< Only walk around
-    RM_Smart                ///> Guess what's better, try to make least mess on the PCB
+    RM_Smart                ///< Guess what's better, try to make least mess on the PCB
 };
 
-///> Optimization effort
+///< Optimization effort.
 enum PNS_OPTIMIZATION_EFFORT
 {
     OE_LOW = 0,
@@ -50,7 +51,7 @@ enum PNS_OPTIMIZATION_EFFORT
     OE_FULL = 2
 };
 
-///> What kind of corners to create in the line placers
+///< What kind of corners to create in the line placers.
 enum class CORNER_MODE
 {
     MITERED_90,     ///< H/V only (90-degree corners) (not yet implemented)
@@ -60,9 +61,7 @@ enum class CORNER_MODE
 };
 
 /**
- * ROUTING_SETTINGS
+ * Contain all persistent settings of the router, such as the mode, optimization effort, etc.
- *
- * Contains all persistent settings of the router, such as the mode, optimization effort, etc.
  */
 
 class ROUTING_SETTINGS : public NESTED_SETTINGS
@@ -70,59 +69,62 @@ class ROUTING_SETTINGS : public NESTED_SETTINGS
 public:
     ROUTING_SETTINGS( JSON_SETTINGS* aParent, const std::string& aPath );
 
-    ///> Returns the routing mode.
+    ///< Return the routing mode.
     PNS_MODE Mode() const { return m_routingMode; }
 
-    ///> Sets the routing mode.
+    ///< Set the routing mode.
     void SetMode( PNS_MODE aMode ) { m_routingMode = aMode; }
 
-    ///> Returns the optimizer effort. Bigger means cleaner traces, but slower routing.
+    ///< Return the optimizer effort. Bigger means cleaner traces, but slower routing.
     PNS_OPTIMIZATION_EFFORT OptimizerEffort() const { return m_optimizerEffort; }
 
-    ///> Sets the optimizer effort. Bigger means cleaner traces, but slower routing.
+    ///< Set the optimizer effort. Bigger means cleaner traces, but slower routing.
     void SetOptimizerEffort( PNS_OPTIMIZATION_EFFORT aEffort ) { m_optimizerEffort = aEffort; }
 
-    ///> Returns true if shoving vias is enbled.
+    ///< Return true if shoving vias is enabled.
     bool ShoveVias() const { return m_shoveVias; }
 
-    ///> Enables/disables shoving vias.
+    ///< Enable/disable shoving vias.
     void SetShoveVias( bool aShoveVias ) { m_shoveVias = aShoveVias; }
 
-    ///> Returns true if loop (redundant track) removal is on.
+    ///< Return true if loop (redundant track) removal is on.
     bool RemoveLoops() const { return m_removeLoops; }
 
-    ///> Enables/disables loop (redundant track) removal.
+    ///< Enable/disable loop (redundant track) removal.
     void SetRemoveLoops( bool aRemoveLoops ) { m_removeLoops = aRemoveLoops; }
 
-    ///> Returns true if suggesting the finish of currently placed track is on.
+    ///< Return true if suggesting the finish of currently placed track is on.
     bool SuggestFinish() { return m_suggestFinish; }
 
-    ///> Enables displaying suggestions for finishing the currently placed track.
+    ///< Enable displaying suggestions for finishing the currently placed track.
     void SetSuggestFinish( bool aSuggestFinish ) { m_suggestFinish = aSuggestFinish; }
 
-    ///> Returns true if Smart Pads (optimized connections) is enabled.
+    ///< Return true if Smart Pads (optimized connections) is enabled.
     bool SmartPads() const { return m_smartPads; }
 
-    ///> Enables/disables Smart Pads (optimized connections).
+    ///< Enable/disable Smart Pads (optimized connections).
     void SetSmartPads( bool aSmartPads ) { m_smartPads = aSmartPads; }
 
-    ///> Returns true if follow mouse mode is active (permanently on for the moment).
+    ///< Return true if follow mouse mode is active (permanently on for the moment).
     bool FollowMouse() const
     {
         return m_followMouse && !( Mode() == RM_MarkObstacles );
     }
 
-    ///> Returns true if smoothing segments durign dragging is enabled.
+    ///< Return true if smoothing segments during dragging is enabled.
     bool SmoothDraggedSegments() const { return m_smoothDraggedSegments; }
 
-    ///> Enables/disabled smoothing segments during dragging.
+    ///< Enable/disable smoothing segments during dragging.
     void SetSmoothDraggedSegments( bool aSmooth ) { m_smoothDraggedSegments = aSmooth; }
 
-    ///> Returns true if jumping over unmovable obstacles is on.
+    ///< Return true if jumping over unmovable obstacles is on.
     bool JumpOverObstacles() const { return m_jumpOverObstacles; }
 
-    ///> Enables/disables jumping over unmovable obstacles.
+    ///< Enable/disable jumping over unmovable obstacles.
-    void SetJumpOverObstacles( bool aJumpOverObstacles ) { m_jumpOverObstacles = aJumpOverObstacles; }
+    void SetJumpOverObstacles( bool aJumpOverObstacles )
+    {
+        m_jumpOverObstacles = aJumpOverObstacles;
+    }
 
     void SetStartDiagonal( bool aStartDiagonal ) { m_startDiagonal = aStartDiagonal; }
 

pcbnew/router/router_tool.cpp

@@ -2,8 +2,9 @@
  * KiRouter - a push-and-(sometimes-)shove PCB router
  *
  * Copyright (C) 2013-2017 CERN
- * Copyright (C) 2017-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
- * Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
+ *
+ * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -63,12 +64,12 @@ enum VIA_ACTION_FLAGS
 {
     // Via type
     VIA_MASK     = 0x03,
-    VIA          = 0x00,     ///> Normal via
+    VIA          = 0x00,     ///< Normal via
-    BLIND_VIA    = 0x01,     ///> blind/buried via
+    BLIND_VIA    = 0x01,     ///< blind/buried via
-    MICROVIA     = 0x02,     ///> Microvia
+    MICROVIA     = 0x02,     ///< Microvia
 
     // Select layer
-    SELECT_LAYER = VIA_MASK + 1,    ///> Ask user to select layer before adding via
+    SELECT_LAYER = VIA_MASK + 1,    ///< Ask user to select layer before adding via
 };
 
 
@@ -502,6 +503,7 @@ void ROUTER_TOOL::handleCommonEvents( const TOOL_EVENT& aEvent )
             for( auto evt : events)
             {
                 wxString id = "null";
+
                 if( evt.item && evt.item->Parent() )
                     id = evt.item->Parent()->m_Uuid.AsString();
 
@@ -972,7 +974,7 @@ bool ROUTER_TOOL::prepareInteractive()
         // It would make more sense to leave the net highlighted as the higher-contrast mode
         // makes the router clearances more visible.  However, since we just started routing
         // the conversion of the screen from low contrast to high contrast is a bit jarring and
-        // makes the infobar coming up less noticable.
+        // makes the infobar coming up less noticeable.
         highlightNet( false );
 
         frame()->ShowInfoBarError( m_router->FailureReason(), true,
@@ -1713,7 +1715,8 @@ int ROUTER_TOOL::InlineBreakTrack( const TOOL_EVENT& aEvent )
     if( selection.Size() != 1 )
         return 0;
 
-    const BOARD_CONNECTED_ITEM* item = static_cast<const BOARD_CONNECTED_ITEM*>( selection.Front() );
+    const BOARD_CONNECTED_ITEM* item =
+            static_cast<const BOARD_CONNECTED_ITEM*>( selection.Front() );
 
     if( item->Type() != PCB_TRACE_T )
         return 0;

pcbnew/tools/board_editor_control.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -35,9 +37,7 @@ namespace KIGFX {
 class PCB_EDIT_FRAME;
 
 /**
- * BOARD_EDITOR_CONTROL
+ * Handle actions specific to the board editor in PcbNew.
- *
- * Handles actions specific to the board editor in pcbnew.
  */
 class BOARD_EDITOR_CONTROL : public PCB_TOOL_BASE
 {
@@ -83,56 +83,53 @@ public:
     // Zone actions
     int ZoneMerge( const TOOL_EVENT& aEvent );
 
-    ///> Duplicates a zone onto a layer (prompts for new layer)
+    ///< Duplicate a zone onto a layer (prompts for new layer)
     int ZoneDuplicate( const TOOL_EVENT& aEvent );
 
     int EditFpInFpEditor( const TOOL_EVENT& aEvent );
 
     /**
-     * Function PlaceTarget()
+     * Allow user to place a layer alignment target.
-     * Allows user to place a layer alignment target.
      */
     int PlaceTarget( const TOOL_EVENT& aEvent );
 
     /**
-     * Function PlaceFootprint()
+     * Display a dialog to select a footprint to be added and allows the user to set its position.
-     * Displays a dialog to select a footprint to be added and allows the user to set its position.
      */
     int PlaceFootprint( const TOOL_EVENT& aEvent );
 
-    ///> Toggles 'lock' property for selected items.
+    ///< Toggle 'lock' property for selected items.
     int ToggleLockSelected( const TOOL_EVENT& aEvent );
 
-    ///> Locks selected items.
+    ///< Lock selected items.
     int LockSelected( const TOOL_EVENT& aEvent );
 
-    ///> Unlocks selected items.
+    ///< Unlock selected items.
     int UnlockSelected( const TOOL_EVENT& aEvent );
 
-    ///> Runs the drill origin tool for setting the origin for drill and pick-and-place files.
+    ///< Run the drill origin tool for setting the origin for drill and pick-and-place files.
     int DrillOrigin( const TOOL_EVENT& aEvent );
 
-    ///> Low-level access (below undo) to setting the drill origin
+    ///< Low-level access (below undo) to setting the drill origin.
     static void DoSetDrillOrigin( KIGFX::VIEW* aView, PCB_BASE_FRAME* aFrame,
                                   EDA_ITEM* aItem, const VECTOR2D& aPoint );
 
     int FlipPcbView( const TOOL_EVENT& aEvent );
 
 private:
-    ///> How to modify a property for selected items.
+    ///< How to modify a property for selected items.
     enum MODIFY_MODE { ON, OFF, TOGGLE };
 
     int modifyLockSelected( MODIFY_MODE aMode );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
-private:
+    PCB_EDIT_FRAME* m_frame;     ///< Pointer to the currently used edit frame.
-    PCB_EDIT_FRAME* m_frame;     ///> Pointer to the currently used edit frame.
 
-    std::unique_ptr<KIGFX::ORIGIN_VIEWITEM> m_placeOrigin;    ///> Place & drill origin marker
+    std::unique_ptr<KIGFX::ORIGIN_VIEWITEM> m_placeOrigin;    ///< Place & drill origin marker
 
-    static const int WIDTH_STEP; ///> How does line width change after one -/+ key press.
+    static const int WIDTH_STEP; ///< How does line width change after one -/+ key press.
 };
 
 #endif

pcbnew/tools/board_inspection_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -51,8 +51,6 @@ protected:
 
 
 /**
- * BOARD_INSPECTION_TOOL
- *
  * Tool for pcb inspection.
  */
 class BOARD_INSPECTION_TOOL : public wxEvtHandler, public PCB_TOOL_BASE
@@ -67,63 +65,61 @@ public:
     void Reset( RESET_REASON aReason ) override;
 
     /**
-     * Function ShowStatisticDialog()
+     * Show dialog with board statistics.
-     *
-     * Shows dialog with board statistics
      */
     int ShowStatisticsDialog( const TOOL_EVENT& aEvent );
 
-    ///> Notifies eeschema about the selected item.
+    ///< Notify Eeschema about the selected item.
     int CrossProbePcbToSch( const TOOL_EVENT& aEvent );
 
-    ///> Highlights net belonging to the item under the cursor.
+    ///< Highlight net belonging to the item under the cursor.
     int HighlightNet( const TOOL_EVENT& aEvent );
 
-    ///> Clears all board highlights
+    ///< Clear all board highlights
     int ClearHighlight( const TOOL_EVENT& aEvent );
 
-    ///> Launches a tool to pick the item whose net is going to be highlighted.
+    ///< Launch a tool to pick the item whose net is going to be highlighted.
     int HighlightNetTool( const TOOL_EVENT& aEvent );
 
-    ///> Performs the appropriate action in response to an eeschema cross-probe.
+    ///< Perform the appropriate action in response to an Eeschema cross-probe.
     int HighlightItem( const TOOL_EVENT& aEvent );
 
-    ///> Updates ratsnest for selected items.
+    ///< Update ratsnest for selected items.
     int UpdateSelectionRatsnest( const TOOL_EVENT& aEvent );
 
-    ///> Hides ratsnest for selected items. Called when there are no items selected.
+    ///< Hide ratsnest for selected items. Called when there are no items selected.
     int HideDynamicRatsnest( const TOOL_EVENT& aEvent );
 
-    ///> Shows local ratsnest of a component
+    ///< Show local ratsnest of a component.
     int LocalRatsnestTool( const TOOL_EVENT& aEvent );
 
     int FlipPcbView( const TOOL_EVENT& aEvent );
 
     int ListNets( const TOOL_EVENT& aEvent );
 
-    ///> Hide the ratsnest for a given net
+    ///< Hide the ratsnest for a given net.
     int HideNet( const TOOL_EVENT& aEvent );
 
-    ///> Show the ratsnest for a given net
+    ///< Show the ratsnest for a given net.
     int ShowNet( const TOOL_EVENT& aEvent );
 
-    ///> Show the clearance resolution for two selected items
+    ///< Show the clearance resolution for two selected items.
     int InspectClearance( const TOOL_EVENT& aEvent );
 
     int InspectConstraints( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Event handler to recalculate dynamic ratsnest
+    ///< Event handler to recalculate dynamic ratsnest.
     void ratsnestTimer( wxTimerEvent& aEvent );
 
-    ///> Recalculates dynamic ratsnest for the current selection
+    ///< Recalculate dynamic ratsnest for the current selection.
     void calculateSelectionRatsnest( const VECTOR2I& aDelta );
 
     bool highlightNet( const VECTOR2D& aPosition, bool aUseSelection );
 
     void doHideNet( int aNetCode, bool aHide );
 
-    ///> Bind handlers to corresponding TOOL_ACTIONs
+    ///< Bind handlers to corresponding TOOL_ACTIONs.
     void setTransitions() override;
 
     void onListNetsDialogClosed( wxCommandEvent& aEvent );
@@ -140,7 +136,7 @@ private:
 private:
     PCB_EDIT_FRAME* m_frame;    // Pointer to the currently used edit frame.
 
-    bool m_probingSchToPcb;     // Recursion guard when cross-probing to EESchema
+    bool m_probingSchToPcb;     // Recursion guard when cross-probing to Eeschema
     int  m_lastNetcode;         // Used for toggling between last two highlighted nets
 
     CONNECTIVITY_DATA* m_dynamicData;      // Cached connectivity data from the selection

pcbnew/tools/convert_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  * @author Jon Evans <jon@craftyjon.com>
  *
  * This program is free software; you can redistribute it and/or
@@ -46,53 +46,57 @@ public:
     bool Init() override;
 
     /**
-     * Converts selected lines to a polygon, if possible
+     * Convert selected lines to a polygon, if possible.
      */
     int LinesToPoly( const TOOL_EVENT& aEvent );
 
     /**
-     * Converts selected polygon-like object to graphic lines, if possible
+     * Convert selected polygon-like object to graphic lines, if possible.
      */
     int PolyToLines( const TOOL_EVENT& aEvent );
 
     /**
-     * Converts selected segment (graphic or track) to an arc of the same type
+     * Convert selected segment (graphic or track) to an arc of the same type
      */
     int SegmentToArc( const TOOL_EVENT& aEvent );
 
-    ///> @copydoc TOOL_INTERACTIVE::setTransitions()
+    ///< @copydoc TOOL_INTERACTIVE::setTransitions()
     void setTransitions() override;
 
 private:
-
     /**
-     * Retrieves the start and end points for a generic item
+     * Retrieve the start and end points for a generic item.
-     * @param aItem is an item that has a start and end point
+     *
-     * @return a segment from start to end, or NULLOPT if invalid
+     * @param aItem is an item that has a start and end point.
+     * @return a segment from start to end, or NULLOPT if invalid.
      */
     static OPT<SEG> getStartEndPoints( EDA_ITEM* aItem );
 
     /**
-     * Tries to make polygons from segments in the selected items.
+     * Try to make polygons from segments in the selected items.
+     *
      * Polygons are formed from chains of lines/arcs.  Each set containing two or more lines/arcs
-     * that are connected will be added to the return SHAPE_POLY_SET as an outline.
+     * that are connected will be added to the return SHAPE_POLY_SET as an outline.  No attempt
-     * No attempt is made to guess at holes.
+     * is made to guess at holes.
-     * @param aItems is a list of items to process
+     *
-     * @return a SHAPE_POLY_SET containing any polygons that were created
+     * @param aItems is a list of items to process.
+     * @return a #SHAPE_POLY_SET containing any polygons that were created.
      */
     static SHAPE_POLY_SET makePolysFromSegs( const std::deque<EDA_ITEM*>& aItems );
 
     /**
-     * Tries to make polygons from rects
+     * Try to make polygons from rectangles.
-     * @param aItems is a list of rect shapes to process
+     *
-     * @return a SHAPE_POLY_SET containing any polygons that were created
+     * @param aItems is a list of rect shapes to process.
+     * @return a #SHAPE_POLY_SET containing any polygons that were created.
      */
     static SHAPE_POLY_SET makePolysFromRects( const std::deque<EDA_ITEM*>& aItems );
 
     /**
-     * Tries to make polygons from circles
+     * Try to make polygons from circles.
-     * @param aItems is a list of circle shapes to process
+     *
-     * @return a SHAPE_POLY_SET containing any polygons that were created
+     * @param aItems is a list of circle shapes to process.
+     * @return a #SHAPE_POLY_SET containing any polygons that were created.
      */
     static SHAPE_POLY_SET makePolysFromCircles( const std::deque<EDA_ITEM*>& aItems );
 

pcbnew/tools/drawing_tool.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014-2017 CERN
- * Copyright (C) 2018-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -36,14 +37,13 @@ namespace KIGFX
     class VIEW;
     class VIEW_CONTROLS;
 }
+
 class BOARD;
 class PCB_BASE_EDIT_FRAME;
 class PCB_SHAPE;
 class POLYGON_GEOM_MANAGER;
 
 /**
- * DRAWING_TOOL
- *
  * Tool responsible for drawing graphical elements like lines, arcs, circles, etc.
  */
 
@@ -59,7 +59,7 @@ public:
     /// @copydoc TOOL_INTERACTIVE::Reset()
     void Reset( RESET_REASON aReason ) override;
 
-    ///> The possible drawing modes of DRAWING_TOOL
+    ///< The possible drawing modes of DRAWING_TOOL
     enum class MODE
     {
         NONE,
@@ -78,149 +78,147 @@ public:
     };
 
     /**
-     * Function GetDrawingMode
+     * Return the current drawing mode of the DRAWING_TOOL or #MODE::NONE if not currently in
-     *
+     * any drawing mode.
-     * Returns the current drawing mode of the DRAWING_TOOL, or
-     * MODE::NONE if not currently in any drawing mode
      */
     MODE GetDrawingMode() const;
 
     /**
-     * Function DrawLine()
+     * Start interactively drawing a line.
-     * Starts interactively drawing a line. After invoking the function it expects the user
+     *
-     * to click at least two times to determine the origin and the end for a line. If there are
+     * After invoking the function it expects the user to click at least two times to determine
-     * more clicks, the line is drawn as a continous polyline.
+     * the origin and the end for a line. If there are more clicks, the line is drawn as a
+     * continuous polyline.
      */
     int DrawLine( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DrawRectangle()
+     * Start interactively drawing a rectangle.
-     * Starts interactively drawing a rectangle. After invoking the function it expects the user
+     *
-     * to first click on a point that is going to be used as the top-left of the rectangle. The
+     * After invoking the function it expects the user to first click on a point that is going
-     * second click determines the bottom-right.
+     * to be used as the top-left of the rectangle. The second click determines the bottom-right.
      */
     int DrawRectangle( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DrawCircle()
+     * Start interactively drawing a circle.
-     * Starts interactively drawing a circle. After invoking the function it expects the user
+     *
-     * to first click on a point that is going to be used as the center of the circle. The second
+     * After invoking the function it expects the user to first click on a point that is going
-     * click determines the circle radius.
+     * to be used as the center of the circle. The second click determines the circle radius.
      */
     int DrawCircle( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DrawArc()
+     * Start interactively drawing an arc.
-     * Starts interactively drawing an arc. After invoking the function it expects the user
+     *
-     * to first click on a point that is going to be used as the center of the arc. The second
+     * After invoking the function it expects the user to first click on a point that is going
-     * click determines the origin and radius, the third one - the angle.
+     * to be used as the center of the arc. The second click determines the origin and radius,
+     * the third one - the angle.
      */
     int DrawArc( const TOOL_EVENT& aEvent );
 
     /**
-     * Function PlaceText()
+     * Display a dialog that allows one to input text and its settings and then lets the user
-     * Displays a dialog that allows one to input text and its settings and then
+     * decide where to place the text in editor.
-     * lets the user decide where to place the text in editor.
      */
     int PlaceText( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DrawDimension()
+     * Start interactively drawing a dimension.
-     * Starts interactively drawing a dimension. After invoking the function it expects the user
+     *
-     * to first click on a point that is going to be used as the origin of the dimension.
+     * After invoking the function it expects the user to first click on a point that is going
-     * The second click determines the end and the third click modifies its height.
+     * to be used as the origin of the dimension.  The second click determines the end and the
+     * third click modifies its height.
      */
     int DrawDimension( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DrawZone()
+     * Start interactively drawing a zone.
-     * Starts interactively drawing a zone. After invoking the function a zone settings dialog
+     *
-     * is displayed. After confirmation it allows the user to set points that are going to be used
+     * After invoking the function a zone settings dialog is displayed. After confirmation it
-     * as a boundary polygon of the zone. Double click or clicking on the origin of the boundary
+     * allows the user to set points that are going to be used as a boundary polygon of the
-     * polyline finishes the drawing.
+     * zone.  Double click or clicking on the origin of the boundary polyline finishes the
+     * drawing.
      *
      * The event parameter indicates which type of zone to draw:
-     *  ADD      add a new zone/keepout with fresh settings
+     *  - ADD      add a new zone/keepout with fresh settings.
-     *  CUTOUT   add a cutout to an existing zone
+     *  - CUTOUT   add a cutout to an existing zone.
-     *  SIMILAR  add a new zone with the same settings as an existing one
+     *  - SIMILAR  add a new zone with the same settings as an existing one.
      */
     int DrawZone(  const TOOL_EVENT& aEvent );
 
     int DrawVia( const TOOL_EVENT& aEvent );
 
     /**
-     * Function PlaceImportedGraphics()
+     * Place a drawing imported from a DXF or SVG file in footprint editor.
-     * Places a drawing imported from a DXF or SVG file in footprint editor.
      */
     int PlaceImportedGraphics( const TOOL_EVENT& aEvent );
 
     /**
-     * Function SetAnchor()
+     * Place the footprint anchor (only in footprint editor).
-     * Places the footprint anchor (only in footprint editor).
      */
     int SetAnchor( const TOOL_EVENT& aEvent );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:
-
     /**
-     * Starts drawing a selected shape (i.e. PCB_SHAPE).
+     * Start drawing a selected shape (i.e. PCB_SHAPE).
+     *
      * @param aGraphic is an object that is going to be used by the tool for drawing. Must be
      *                 already created. The tool deletes the object if it is not added to a BOARD.
      * @param aStartingPoint is a starting point for this new PCB_SHAPE. If it exists the new
      *                       item has its start point set to aStartingPoint, and its settings
      *                       (width, layer) set to the current default values.
-     * @return False if the tool was cancelled before the origin was set or origin and end are
+     * @return False if the tool was canceled before the origin was set or origin and end are
      *         the same point.
      */
     bool drawSegment( const std::string& aTool, PCB_SHAPE** aGraphic,
                       OPT<VECTOR2D> aStartingPoint );
 
     /**
-     * Starts drawing an arc.
+     * Start drawing an arc.
+     *
      * @param aGraphic is an object that is going to be used by the tool for drawing. Must be
      *                 already created. The tool deletes the object if it is not added to a BOARD.
-     * @return False if the tool was cancelled before the origin was set or origin and end are
+     * @return False if the tool was canceled before the origin was set or origin and end are
      *         the same point.
      */
     bool drawArc( const std::string& aTool, PCB_SHAPE** aGraphic, bool aImmediateMode );
 
     /**
-     * Draws a polygon, that is added as a zone or a keepout area.
+     * Draw a polygon, that is added as a zone or a keepout area.
      *
-     * @param aKeepout dictates if the drawn polygon is a zone or a
+     * @param aKeepout dictates if the drawn polygon is a zone or a keepout area.
-     * keepout area.
      * @param aMode dictates the mode of the zone tool:
-     *  ADD      add a new zone/keepout with fresh settings
+     *  - ADD      add a new zone/keepout with fresh settings
-     *  CUTOUT   add a cutout to an existing zone
+     *  - CUTOUT   add a cutout to an existing zone
-     *  SIMILAR  add a new zone with the same settings as an existing one
+     *  - SIMILAR  add a new zone with the same settings as an existing one
      */
 
     /**
-     * Function getSourceZoneForAction()
+     * Get a source zone item for an action that takes an existing zone into account (for
+     * example a cutout of an existing zone).
      *
-     * Gets a source zone item for an action that takes an existing zone
+     * The source zone is taken from the current selection.
-     * into account (for example a cutout of an existing zone). The source
-     * zone is taken from the current selection
      *
      * @param aMode mode of the zone tool
-     * @param aZone updated pointer to a suitable source zone,
+     * @param aZone updated pointer to a suitable source zone, or nullptr if none found, or
-     * or nullptr if none found, or the action doesn't need a source
+     *              the action doesn't need a source
-     * @return true if a suitable zone was found, or the action doesn't
+     * @return true if a suitable zone was found, or the action doesn't need a zone. False if
-     * need a zone. False if the action needs a zone but none was found.
+     *         the action needs a zone but none was found.
      */
     bool getSourceZoneForAction( ZONE_MODE aMode, ZONE** aZone );
 
     /**
-     * Function constrainDimension()
+     * Force the dimension lime to be drawn on multiple of 45 degrees.
-     * Forces the dimension lime to be drawn on multiple of 45 degrees
+     *
-     * @param aDimension is the dimension element currently being drawn
+     * @param aDimension is the dimension element currently being drawn.
      */
     void constrainDimension( DIMENSION_BASE* aDim );
 
-    ///> Returns the appropriate width for a segment depending on the settings.
+    ///< Return the appropriate width for a segment depending on the settings.
     int getSegmentWidth( PCB_LAYER_ID aLayer ) const;
 
     KIGFX::VIEW*              m_view;

pcbnew/tools/drc_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2020 KiCad Developers, see change_log.txt for contributors.
+ * Copyright (C) 2020-2021 KiCad Developers, see change_log.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -51,29 +51,6 @@ public:
     /// @copydoc TOOL_INTERACTIVE::Reset()
     void Reset( RESET_REASON aReason ) override;
 
-private:
-    PCB_EDIT_FRAME*  m_editFrame;        // The pcb frame editor which owns the board
-    BOARD*           m_pcb;
-    DIALOG_DRC*      m_drcDialog;
-    bool             m_drcRunning;
-
-    std::shared_ptr<DRC_ENGINE>            m_drcEngine;
-
-    std::vector<std::shared_ptr<DRC_ITEM>> m_unconnected;      // list of unconnected pads
-    std::vector<std::shared_ptr<DRC_ITEM>> m_footprints;       // list of footprint warnings
-
-private:
-    ///> Sets up handlers for various events.
-    void setTransitions() override;
-
-    /**
-     * Update needed pointers from the one pointer which is known not to change.
-     */
-    void updatePointers();
-
-    EDA_UNITS userUnits() const { return m_editFrame->GetUserUnits(); }
-
-public:
     /**
      * Open a dialog and prompts the user, then if a test run button is
      * clicked, runs the test(s) and creates the MARKERS.  The dialog is only
@@ -106,7 +83,7 @@ public:
     bool IsDRCRunning() const { return m_drcRunning; }
 
     /**
-     * Closes and frees the DRC dialog.
+     * Close and free the DRC dialog.
      */
     void DestroyDRCDialog();
 
@@ -121,6 +98,27 @@ public:
     int PrevMarker( const TOOL_EVENT& aEvent );
     int NextMarker( const TOOL_EVENT& aEvent );
     int ExcludeMarker( const TOOL_EVENT& aEvent );
+
+private:
+    ///< Set up handlers for various events.
+    void setTransitions() override;
+
+    /**
+     * Update needed pointers from the one pointer which is known not to change.
+     */
+    void updatePointers();
+
+    EDA_UNITS userUnits() const { return m_editFrame->GetUserUnits(); }
+
+    PCB_EDIT_FRAME*  m_editFrame;        // The pcb frame editor which owns the board
+    BOARD*           m_pcb;
+    DIALOG_DRC*      m_drcDialog;
+    bool             m_drcRunning;
+
+    std::shared_ptr<DRC_ENGINE>            m_drcEngine;
+
+    std::vector<std::shared_ptr<DRC_ITEM>> m_unconnected;      // list of unconnected pads
+    std::vector<std::shared_ptr<DRC_ITEM>> m_footprints;       // list of footprint warnings
 };
 
 

pcbnew/tools/edit_tool.h

@@ -3,6 +3,7 @@
  *
  * Copyright (C) 2013-2020 CERN
  * Copyright (C) 2013-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  *
@@ -54,10 +55,10 @@ public:
 };
 
 /**
- * EDIT_TOOL
+ * The interactive edit tool.
  *
- * The interactive edit tool. Allows one to move, rotate, flip and change properties of items s
+ * Allows one to move, rotate, flip and change properties of items selected using the
- * elected using the pcbnew.InteractiveSelection tool.
+ * pcbnew.InteractiveSelection tool.
  */
 
 class EDIT_TOOL : public PCB_TOOL_BASE
@@ -71,99 +72,85 @@ public:
     /// @copydoc TOOL_INTERACTIVE::Init()
     bool Init() override;
 
-    ///> Find an item and start moving.
+    ///< Find an item and start moving.
     int GetAndPlace( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Move()
      * Main loop in which events are handled.
      */
     int Move( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Drag()
      * Invoke the PNS router to drag tracks or do an offline resizing of an arc track
-     * if a single arc track is selected
+     * if a single arc track is selected.
      */
     int Drag( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DragArcTrack()
+     * Drag-resize an arc (and change end points of connected straight segments).
-     * Drag-resize an arc (and change end points of connected straight segments)
      */
     int DragArcTrack( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Properties()
+     * Display properties window for the selected object.
-     * Displays properties window for the selected object.
      */
     int Properties( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Rotate()
+     * Rotate currently selected items.
-     * Rotates currently selected items.
      */
     int Rotate( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Flip()
+     * Rotate currently selected items. The rotation point is the current cursor position.
-     * Rotates currently selected items. The rotation point is the current cursor position.
      */
     int Flip( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Mirror
+     * Mirror the current selection. The mirror axis passes through the current point.
-     * Mirrors the current selection. The mirror axis passes through the current point.
      */
     int Mirror( const TOOL_EVENT& aEvent );
 
     int ChangeTrackWidth( const TOOL_EVENT& aEvent );
 
     /**
-     * Function FilletTracks()
+     * Fillet (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius.
-     * Fillets (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius
      */
     int FilletTracks( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Remove()
+     * Delete currently selected items.
-     * Deletes currently selected items. The rotation point is the current cursor position.
      */
     int Remove( const TOOL_EVENT& aEvent );
 
     /**
-     * Function Duplicate()
+     * Duplicate the current selection and starts a move action.
-     * Duplicates the current selection and starts a move action.
      */
     int Duplicate( const TOOL_EVENT& aEvent );
 
     /**
-     * Function MoveExact()
+     * Invoke a dialog box to allow moving of the item by an exact amount.
-     * Invokes a dialog box to allow moving of the item by an exact amount.
      */
     int MoveExact( const TOOL_EVENT& aEvent );
 
     /**
-     * Moves an item but with a reference point selected first
+     * Move an item but with a reference point selected first
      */
     int MoveWithReference( const TOOL_EVENT& aEvent );
 
     /**
-     * Function CreateArray()
+     * Create an array of the selected items, invoking the array editor dialog to set the options.
-     * Creates an array of the selected items, invoking the array editor dialog to set the options.
      */
     int CreateArray( const TOOL_EVENT& aEvent );
 
     /**
-     * Function FootprintFilter()
+     * A selection filter which prunes the selection to contain only items of type #PCB_MODULE_T.
-     * A selection filter which prunes the selection to contain only items of type PCB_MODULE_T
      */
     static void FootprintFilter( const VECTOR2I&, GENERAL_COLLECTOR& aCollector,
                                  PCB_SELECTION_TOOL* sTool );
 
     /**
-     * Function PadFilter()
+     * A selection filter which prunes the selection to contain only items of type #PCB_PAD_T.
-     * A selection filter which prunes the selection to contain only items of type PCB_PAD_T
      */
     static void PadFilter( const VECTOR2I&, GENERAL_COLLECTOR& aCollector,
                            PCB_SELECTION_TOOL* sTool );
@@ -171,25 +158,23 @@ public:
     BOARD_COMMIT* GetCurrentCommit() const { return m_commit.get(); }
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
     /**
-     * Function copyToClipboard()
+     * Send the current selection to the clipboard by formatting it as a fake pcb
-     * Sends the current selection to the clipboard by formatting it as a fake pcb
+     * see #AppendBoardFromClipboard for importing.
-     * see AppendBoardFromClipboard for importing
      */
     int copyToClipboard( const TOOL_EVENT& aEvent );
 
     /**
-     * Function cutToClipboard()
+     * Cut the current selection to the clipboard by formatting it as a fake pcb
-     * Cuts the current selection to the clipboard by formatting it as a fake pcb
+     * see #AppendBoardFromClipboard for importing.
-     * see AppendBoardFromClipboard for importing
      */
     int cutToClipboard( const TOOL_EVENT& aEvent );
 
-    ///> Returns the right modification point (e.g. for rotation), depending on the number of
+    ///< Return the right modification point (e.g. for rotation), depending on the number of
-    ///> selected items.
+    ///< selected items.
     bool updateModificationPoint( PCB_SELECTION& aSelection );
 
     bool invokeInlineRouter( int aDragMode );

pcbnew/tools/footprint_editor_control.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -32,8 +34,6 @@ class FOOTPRINT_EDIT_FRAME;
 class DIALOG_FOOTPRINT_CHECKER;
 
 /**
- * FOOTPRINT_EDITOR_CONTROL
- *
  * Module editor specific tools.
  */
 class FOOTPRINT_EDITOR_CONTROL : public PCB_TOOL_BASE
@@ -78,10 +78,9 @@ public:
     int DefaultPadProperties( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
-private:
     FOOTPRINT_EDIT_FRAME*      m_frame;
     DIALOG_FOOTPRINT_CHECKER*  m_checkerDialog;
 

pcbnew/tools/global_edit_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2019 KiCad Developers, see AUTHORS.TXT for contributors.
+ * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.TXT for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -47,10 +47,10 @@ public:
     bool Init() override;
 
     /**
-     * Function ExchangeFootprints()
-     *
      * Invoke the dialog used to update or exchange the footprint definitions used for
-     * footprints.  The mode depends on the PCB_ACTIONS held by the TOOL_EVENT.
+     * footprints.
+     *
+     * The mode depends on the #PCB_ACTIONS held by the #TOOL_EVENT.
      */
     int ExchangeFootprints( const TOOL_EVENT& aEvent );
 
@@ -66,7 +66,7 @@ public:
 private:
     bool swapBoardItem( BOARD_ITEM* aItem, PCB_LAYER_ID* aLayerMap );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:

pcbnew/tools/group_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -47,32 +47,29 @@ public:
     int GroupProperties( const TOOL_EVENT& aEvent );
 
     /**
-     * Function SelectNewMember()
+     * Invoke the picker tool to select a new member of the group.
-     *
-     * Invokes the picker tool to select a new member of the group.
      */
     int PickNewMember( const TOOL_EVENT& aEvent  );
 
-    ///> Groups selected items.
+    ///< Group selected items.
     int Group( const TOOL_EVENT& aEvent );
 
-    ///> Ungroups selected items.
+    ///< Ungroup selected items.
     int Ungroup( const TOOL_EVENT& aEvent );
 
-    ///> Remove selection from group.
+    ///< Remove selection from group.
     int RemoveFromGroup( const TOOL_EVENT& aEvent );
 
-    ///> Restrict seletion to only member of the group.
+    ///< Restrict selection to only member of the group.
     int EnterGroup( const TOOL_EVENT& aEvent );
 
-    ///> Leave the current group (deselect its members and select the group as a whole)
+    ///< Leave the current group (deselect its members and select the group as a whole).
     int LeaveGroup( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
-private:
     PCB_BASE_EDIT_FRAME*          m_frame;
     DIALOG_GROUP_PROPERTIES*      m_propertiesDialog;
     PCB_SELECTION_TOOL*           m_selectionTool;

pcbnew/tools/pad_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -30,9 +30,7 @@
 class ACTION_MENU;
 
 /**
- * PAD_TOOL
+ * Tool relating to pads and pad settings.
- *
- * Tools relating to pads and pad settings
  */
 class PAD_TOOL : public PCB_TOOL_BASE
 {
@@ -40,26 +38,24 @@ public:
     PAD_TOOL();
     ~PAD_TOOL();
 
-    ///> React to model/view changes
+    ///< React to model/view changes
     void Reset( RESET_REASON aReason ) override;
 
-    ///> Basic initalization
+    ///< Basic initialization
     bool Init() override;
 
     /**
-     * Function EnumeratePads()
      * Tool for quick pad enumeration.
      */
     int EnumeratePads( const TOOL_EVENT& aEvent );
 
     /**
-     * Function PlacePad()
+     * Place a pad in footprint editor.
-     * Places a pad in footprint editor.
      */
     int PlacePad( const TOOL_EVENT& aEvent );
 
     /**
-     * Enters/exits WYSIWYG pad shape editing
+     * Enter/exit WYSIWYG pad shape editing.
      */
     int EditPad( const TOOL_EVENT& aEvent );
 
@@ -67,22 +63,21 @@ public:
     void SetLastPadName( const wxString& aPadName ) { m_lastPadName = aPadName; }
 
 private:
-    ///> Bind handlers to corresponding TOOL_ACTIONs
+    ///< Bind handlers to corresponding TOOL_ACTIONs.
     void setTransitions() override;
 
-    ///> Apply pad settings from board design settings to a pad
+    ///< Apply pad settings from board design settings to a pad.
     int pastePadProperties( const TOOL_EVENT& aEvent );
 
-    ///> Copy pad settings from a pad to the board design settings
+    ///< Copy pad settings from a pad to the board design settings.
     int copyPadSettings( const TOOL_EVENT& aEvent );
 
-    ///> Push pad settings from a pad to other pads on board or footprint
+    ///< Push pad settings from a pad to other pads on board or footprint.
     int pushPadSettings( const TOOL_EVENT& aEvent );
 
     PCB_LAYER_ID explodePad( PAD* aPad );
     void recombinePad( PAD* aPad );
 
-private:
     wxString       m_lastPadName;
     bool           m_padCopied;    // Indicates there are valid settings in the Master Pad object
 

pcbnew/tools/pcb_actions.h

@@ -2,7 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2013-2016 CERN
- * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -43,10 +44,10 @@ enum class ZONE_MODE
 
 
 /**
- * PCB_ACTIONS
+ * Gather all the actions that are shared by tools.
  *
- * Gathers all the actions that are shared by tools. The instance of PCB_ACTIONS is created
+ * The instance of PCB_ACTIONS is created inside of #ACTION_MANAGER object that registers
- * inside of ACTION_MANAGER object that registers the actions.
+ * the actions.
  */
 class PCB_ACTIONS : public ACTIONS
 {
@@ -58,37 +59,37 @@ public:
     /// Select a single item under the cursor position
     static TOOL_ACTION selectionCursor;
 
-    /// Clears the current selection
+    /// Clear the current selection
     static TOOL_ACTION selectionClear;
 
-    /// Selects an item (specified as the event parameter).
+    /// Select an item (specified as the event parameter).
     static TOOL_ACTION selectItem;
     static TOOL_ACTION unselectItem;
 
-    /// Selects a list of items (specified as the event parameter)
+    /// Select a list of items (specified as the event parameter)
     static TOOL_ACTION selectItems;
     static TOOL_ACTION unselectItems;
 
-    /// Runs a selection menu to select from a list of items
+    /// Run a selection menu to select from a list of items
     static TOOL_ACTION selectionMenu;
 
-    /// Selects tracks between junctions or expands an existing selection to pads or the
+    /// Select tracks between junctions or expands an existing selection to pads or the
     /// entire connection.
     static TOOL_ACTION selectConnection;
 
-    /// Selects all connections belonging to a single net.
+    /// Select all connections belonging to a single net.
     static TOOL_ACTION selectNet;
 
-    /// Removes all connections belonging to a single net from the active selection
+    /// Remove all connections belonging to a single net from the active selection
     static TOOL_ACTION deselectNet;
 
-    /// Selects all components on sheet from Eeschema crossprobing.
+    /// Select all components on sheet from Eeschema crossprobing.
     static TOOL_ACTION selectOnSheetFromEeschema;
 
-    /// Selects all components on the same sheet as the selected footprint.
+    /// Select all components on the same sheet as the selected footprint.
     static TOOL_ACTION selectSameSheet;
 
-    /// Filters the items in the current selection (invokes dialog)
+    /// Filter the items in the current selection (invokes dialog)
     static TOOL_ACTION filterSelection;
 
     /// move or drag an item
@@ -110,10 +111,10 @@ public:
     /// Mirroring of selected items
     static TOOL_ACTION mirror;
 
-    /// Updates selected tracks & vias to the current track & via dimensions
+    /// Update selected tracks & vias to the current track & via dimensions
     static TOOL_ACTION changeTrackWidth;
 
-    /// Fillets (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius
+    /// Fillet (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius
     static TOOL_ACTION filletTracks;
 
     /// Activation of the edit tool
@@ -469,7 +470,7 @@ public:
     static TOOL_ACTION convertToArc;
     static TOOL_ACTION convertToTracks;
 
-    ///> @copydoc COMMON_ACTIONS::TranslateLegacyId()
+    ///< @copydoc COMMON_ACTIONS::TranslateLegacyId()
     virtual OPT<TOOL_EVENT> TranslateLegacyId( int aId ) override;
 };
 

pcbnew/tools/pcb_control.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014-2016 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -35,10 +37,9 @@ namespace KIGFX {
 
 class PCB_BASE_FRAME;
 class BOARD_ITEM;
+
 /**
- * PCB_CONTROL
+ * Handle actions that are shared between different frames in PcbNew.
- *
- * Handles actions that are shared between different frames in pcbnew.
  */
 
 class PCB_CONTROL : public PCB_TOOL_BASE
@@ -92,12 +93,13 @@ public:
     int AppendBoard( PLUGIN& pi, wxString& fileName );
     int UpdateMessagePanel( const TOOL_EVENT& aEvent );
 
-    ///> Sets up handlers for various events.
+    ///< Sets up handlers for various events.
     void setTransitions() override;
 
 private:
     /**
      * Add and select or just select for move/place command a list of board items.
+     *
      * @param aItems is the list of items
      * @param aIsNew = true to add items to the current board, false to just select if
      *               items are already managed by the current board
@@ -108,10 +110,10 @@ private:
 
     int placeBoardItems( BOARD* aBoard, bool aAnchorAtOrigin );
 
-    ///> Pointer to the currently used edit frame.
+    ///< Pointer to the currently used edit frame.
     PCB_BASE_FRAME* m_frame;
 
-    ///> Grid origin marker.
+    ///< Grid origin marker.
     std::unique_ptr<KIGFX::ORIGIN_VIEWITEM> m_gridOrigin;
 
     BOARD_ITEM* m_pickerItem;

pcbnew/tools/pcb_editor_conditions.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2020 Ian McInerney <ian.s.mcinerney at ieee.org>
- * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -35,7 +35,7 @@ class EDA_DRAW_FRAME;
 class PCB_BASE_FRAME;
 
 /**
- * Class that groups generic conditions for PCB editor states.
+ * Group generic conditions for PCB editor states.
  */
 class PCB_EDITOR_CONDITIONS : public EDITOR_CONDITIONS
 {
@@ -45,56 +45,56 @@ public:
     {}
 
     /**
-     * Creates a functor that tests if there are items in the board
+     * Create a functor that tests if there are items in the board
      *
      * @return Functor returning true if the the current board has items
      */
     SELECTION_CONDITION HasItems();
 
     /**
-     * Creates a functor that tests if the pad numbers are displayed
+     * Create a functor that tests if the pad numbers are displayed
      *
      * @return Functor returning true if the pad numbers are displayed
      */
     SELECTION_CONDITION PadNumbersDisplay();
 
     /**
-     * Creates a functor that tests if the frame fills the pads
+     * Create a functor that tests if the frame fills the pads
      *
      * @return Functor returning true if the pads are filled
      */
     SELECTION_CONDITION PadFillDisplay();
 
     /**
-     * Creates a functor that tests if the frame fills text items
+     * Create a functor that tests if the frame fills text items
      *
      * @return Functor returning true if the text items are filled
      */
     SELECTION_CONDITION TextFillDisplay();
 
     /**
-     * Creates a functor that tests if the frame fills graphics items
+     * Create a functor that tests if the frame fills graphics items
      *
      * @return Functor returning true if graphics items are filled
      */
     SELECTION_CONDITION GraphicsFillDisplay();
 
     /**
-     * Creates a functor that tests if the frame fills vias
+     * Create a functor that tests if the frame fills vias
      *
      * @return Functor returning true if vias are filled
      */
     SELECTION_CONDITION ViaFillDisplay();
 
     /**
-     * Creates a functor that tests if the frame fills vias
+     * Create a functor that tests if the frame fills vias
      *
      * @return Functor returning true if tracks are filled
      */
     SELECTION_CONDITION TrackFillDisplay();
 
     /**
-     * Creates a functor that tests the current zone display mode in the frame
+     * Create a functor that tests the current zone display mode in the frame
      *
      * @param aMode is the mode to test for
      * @return Functor returning true if the frame is using the specified mode
@@ -102,28 +102,28 @@ public:
     SELECTION_CONDITION ZoneDisplayMode( ZONE_DISPLAY_MODE aMode );
 
 protected:
-    ///> Helper function used by HasItems()
+    ///< Helper function used by HasItems()
     static bool hasItemsFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by PadNumbersDisplay()
+    ///< Helper function used by PadNumbersDisplay()
     static bool padNumberDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by PadFillDisplay()
+    ///< Helper function used by PadFillDisplay()
     static bool padFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by TextFillDisplay()
+    ///< Helper function used by TextFillDisplay()
     static bool textFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by GraphicsFillDisplay()
+    ///< Helper function used by GraphicsFillDisplay()
     static bool graphicsFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by ViaFillDisplay()
+    ///< Helper function used by ViaFillDisplay()
     static bool viaFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by TrackFillDisplay()
+    ///< Helper function used by TrackFillDisplay()
     static bool trackFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame );
 
-    ///> Helper function used by ZoneDisplayMode()
+    ///< Helper function used by ZoneDisplayMode()
     static bool zoneDisplayModeFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame,
                                      ZONE_DISPLAY_MODE aMode );
 };

pcbnew/tools/pcb_picker_tool.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2015 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -29,7 +31,7 @@
 #include <tools/pcb_tool_base.h>
 
 /**
- * @brief Generic tool for picking an item.
+ *Generic tool for picking an item.
  */
 class PCB_PICKER_TOOL : public PCB_TOOL_BASE
 {
@@ -37,7 +39,7 @@ public:
     PCB_PICKER_TOOL();
     ~PCB_PICKER_TOOL() override { }
 
-    ///> Event handler types.
+    ///< Event handler types.
     typedef std::function<bool(const VECTOR2D&)> CLICK_HANDLER;
     typedef std::function<void(const VECTOR2D&)> MOTION_HANDLER;
     typedef std::function<void(void)> CANCEL_HANDLER;
@@ -52,15 +54,14 @@ public:
         EXCEPTION_CANCEL
     };
 
-    ///> @copydoc TOOL_INTERACTIVE::Reset()
+    ///< @copydoc TOOL_INTERACTIVE::Reset()
     void Reset( RESET_REASON aReason ) override {}
 
-    ///> Main event loop.
+    ///< Main event loop.
     int Main( const TOOL_EVENT& aEvent );
 
     /**
-     * Function SetLayerSet()
+     * Set the tool's snap layer set.
-     * Sets the tool's snap layer set
      */
     inline void SetLayerSet( LSET aLayerSet ) { m_layerMask = aLayerSet; }
 
@@ -68,8 +69,7 @@ public:
 
     inline void SetSnapping( bool aSnap ) { m_snap = aSnap; }
     /**
-     * Function SetClickHandler()
+     * Set a handler for mouse click event. Handler may decide to receive further click by
-     * Sets a handler for mouse click event. Handler may decide to receive further click by
      * returning true.
      */
     inline void SetClickHandler( CLICK_HANDLER aHandler )
@@ -79,8 +79,7 @@ public:
     }
 
     /**
-     * Function SetMotionHandler()
+     * Set a handler for mouse motion.  Used for roll-over highlighting.
-     * Sets a handler for mouse motion.  Used for roll-over highlighting.
      */
     inline void SetMotionHandler( MOTION_HANDLER aHandler )
     {
@@ -89,8 +88,7 @@ public:
     }
 
     /**
-     * Function SetCancelHandler()
+     * Set a handler for cancel events (ESC or context-menu Cancel).
-     * Sets a handler for cancel events (ESC or context-menu Cancel).
      */
     inline void SetCancelHandler( CANCEL_HANDLER aHandler )
     {
@@ -99,8 +97,7 @@ public:
     }
 
     /**
-     * Function SetFinalizeHandler()
+     * Set a handler for the finalize event. Takes the state of the exit from the Main loop.
-     * Sets a handler for the finalize event. Takes the state of the exit from the Main loop
      */
     inline void SetFinalizeHandler( FINALIZE_HANDLER aHandler )
     {
@@ -108,18 +105,17 @@ public:
         m_finalizeHandler = aHandler;
     }
 
-private:
+    ///< @copydoc TOOL_INTERACTIVE::setTransitions();
-    ///> @copydoc TOOL_INTERACTIVE::setTransitions();
     void setTransitions() override;
 
-    ///> Reinitializes tool to its initial state.
+    ///< Reinitialize tool to its initial state.
     void reset();
 
-    ///> Applies the requested VIEW_CONTROLS settings.
+    ///< Apply the requested VIEW_CONTROLS settings.
     void setControls();
 
 private:
-    ///> The layer set to use for optional snapping
+    ///< The layer set to use for optional snapping.
     LSET                  m_layerMask;
     KICURSOR              m_cursor;
     bool                  m_snap;

pcbnew/tools/pcb_point_editor.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2013-2017 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -36,8 +38,6 @@ class PCB_SELECTION_TOOL;
 class SHAPE_POLY_SET;
 
 /**
- * PCB_POINT_EDITOR
- *
  * Tool that displays edit points allowing to modify items by dragging the points.
  */
 class PCB_POINT_EDITOR : public PCB_TOOL_BASE
@@ -52,46 +52,46 @@ public:
     bool Init() override;
 
     /**
-     * Function OnSelected()
-     *
      * Change selection event handler.
      */
     int OnSelectionChange( const TOOL_EVENT& aEvent );
 
     /**
-     * Indicates the cursor is over an edit point.  Used to coordinate cursor shapes with
+     * Indicate the cursor is over an edit point.
-     * other tools.
+     *
+     * Used to coordinate cursor shapes with other tools.
      */
     bool HasPoint() { return m_editedPoint != nullptr; }
 
 private:
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
     void buildForPolyOutline( std::shared_ptr<EDIT_POINTS> points, const SHAPE_POLY_SET* aOutline );
 
     std::shared_ptr<EDIT_POINTS> makePoints( EDA_ITEM* aItem );
 
-    ///> Updates item's points with edit points.
+    ///< Update item's points with edit points.
     void updateItem() const;
 
-    ///> Applies the last changes to the edited item.
+    ///< Apply the last changes to the edited item.
     void finishItem();
 
     /**
-     * Validates a polygon and displays a popup warning if invalid.
+     * Validate a polygon and displays a popup warning if invalid.
+     *
      * @param aModified is the polygon to be checked.
      * @return True if polygon is valid.
      */
     bool validatePolygon( SHAPE_POLY_SET& aModified ) const;
 
-    ///> Updates edit points with item's points.
+    ///< Update edit points with item's points.
     void updatePoints();
 
-    ///> Updates which point is being edited.
+    ///< Update which point is being edited.
     void updateEditedPoint( const TOOL_EVENT& aEvent );
 
-    ///> Sets the current point being edited. NULL means none.
+    ///< Set the current point being edited. NULL means none.
     void setEditedPoint( EDIT_POINT* aPoint );
 
     inline int getEditedPointIndex() const
@@ -105,25 +105,25 @@ private:
         return wxNOT_FOUND;
     }
 
-    ///> Returns true if aPoint is the currently modified point.
+    ///< Return true if aPoint is the currently modified point.
     inline bool isModified( const EDIT_POINT& aPoint ) const
     {
         return m_editedPoint == &aPoint;
     }
 
-    ///> Sets up an alternative constraint (typically enabled upon a modifier key being pressed).
+    ///< Set up an alternative constraint (typically enabled upon a modifier key being pressed).
     void setAltConstraint( bool aEnabled );
 
-    ///> Returns a point that should be used as a constrainer for 45 degrees mode.
+    ///< Return a point that should be used as a constrainer for 45 degrees mode.
     EDIT_POINT get45DegConstrainer() const;
 
-    ///> Condition to display "Create corner" context menu entry.
+    ///< Condition to display "Create corner" context menu entry.
     static bool addCornerCondition( const SELECTION& aSelection );
 
-    ///> Determine if the tool can currently add a corner to the given item
+    ///< Determine if the tool can currently add a corner to the given item
     static bool canAddCorner( const EDA_ITEM& aItem );
 
-    ///> Condition to display "Remove corner" context menu entry.
+    ///< Condition to display "Remove corner" context menu entry.
     bool removeCornerCondition( const SELECTION& aSelection );
 
     /// TOOL_ACTION handlers
@@ -155,10 +155,9 @@ private:
     void editArcMidKeepCenter( PCB_SHAPE* aArc, VECTOR2I aCenter, VECTOR2I aStart, VECTOR2I aMid,
                                VECTOR2I aEnd, const VECTOR2I aCursor ) const;
 
-    ///> Change the edit method to an alternative method ( currently, arcs only )
+    ///< Change the edit method to an alternative method ( currently, arcs only )
     int changeEditMethod( const TOOL_EVENT& aEvent );
 
-private:
     PCB_SELECTION_TOOL*                m_selectionTool;
     std::unique_ptr<STATUS_TEXT_POPUP> m_statusPopup;
     std::shared_ptr<EDIT_POINTS>       m_editPoints;
@@ -166,7 +165,7 @@ private:
     EDIT_POINT*         m_editedPoint;
     EDIT_POINT*         m_hoveredPoint;
 
-    EDIT_POINT          m_original;        ///> Original position for the current drag point.
+    EDIT_POINT          m_original;        ///< Original position for the current drag point.
 
     bool                m_refill;
     bool                m_altEditMethod;

pcbnew/tools/pcb_selection_conditions.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -34,17 +36,17 @@ class PCB_SELECTION_CONDITIONS : public SELECTION_CONDITIONS
 {
 public:
     /**
-     * Function OnlyConnectedItems
+     * Test if selection contains exclusively connected items (pads, tracks, vias, zones).
-     * Tests if selection contains exclusively connected items (pads, tracks, vias, zones).
+     *
      * @param aSelection is the selection to be tested.
      * @return True if there are only connected items connected.
      */
     static bool OnlyConnectedItems( const SELECTION& aSelection );
 
     /**
-     * Function SameNet
+     * Create a functor that tests if selection contains items belonging to the same net or are
-     * Creates a functor that tests if selection contains items belonging to the same net or are
      * unconnected if aAllowUnconnected == true.
+     *
      * @param aAllowUnconnected determines if unconnected items (with no net code assigned) should
      *                          be treated as connected to the same net.
      * @return Functor testing if selected items are belonging to the same net.
@@ -52,17 +54,21 @@ public:
     static SELECTION_CONDITION SameNet( bool aAllowUnconnected = false );
 
     /**
-     * Function SameLayer
      * Creates a functor that tests if selection contains items that belong exclusively to the same
-     * layer. In case of items belonging to multiple layers, it is enough to have a single common
+     * layer.
-     * layer with other items.
+     *
+     * In case of items belonging to multiple layers, it is enough to have a single common layer
+     * with other items.
+     *
      * @return Functor testing if selected items share at least one common layer.
      */
     static SELECTION_CONDITION SameLayer();
 
     /**
-     * Creates a functor that tests if the selection contains PCB_SHAPE* items of certain shapes
+     * Create a functor that tests if the selection contains PCB_SHAPE* items of certain shapes.
-     * This implicitly includes an OnlyType( PCB_SHAPE_T ) as part of the test
+     *
+     * This implicitly includes an OnlyType( PCB_SHAPE_T ) as part of the test.
+     *
      * @param aTypes is a list of allowed PCB_SHAPE shapes (@see PCB_SHAPE_TYPE_T)
      * @return functor testing if selected items match the given list of allowed shapes
      */
@@ -70,13 +76,13 @@ public:
 
 
 private:
-    ///> Helper function used by SameNet()
+    ///< Helper function used by SameNet()
     static bool sameNetFunc( const SELECTION& aSelection, bool aAllowUnconnected );
 
-    ///> Helper function used by SameLayer()
+    ///< Helper function used by SameLayer()
     static bool sameLayerFunc( const SELECTION& aSelection );
 
-    ///> Helper function used by OnlyGraphicShapeTypes()
+    ///< Helper function used by OnlyGraphicShapeTypes()
     static bool onlyGraphicShapeTypesFunc( const SELECTION& aSelection,
                                            const std::set<PCB_SHAPE_TYPE_T> aTypes );
 };

pcbnew/tools/pcb_selection_tool.h

@@ -2,9 +2,10 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2013-2017 CERN
+ * Copyright (C) 2017-2021 KiCad Developers, see CHANGELOG.TXT for contributors.
+ *
  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
  * @author Maciej Suminski <maciej.suminski@cern.ch>
- * Copyright (C) 2017-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -51,9 +52,7 @@ typedef void (*CLIENT_SELECTION_FILTER)( const VECTOR2I&, GENERAL_COLLECTOR&, PC
 
 
 /**
- * PCB_SELECTION_TOOL
+ * The selection tool: currently supports:
- *
- * Our sample selection tool: currently supports:
  * - pick single objects (click LMB)
  * - add objects to existing selection (Shift+LMB)
  * - draw selection box (drag LMB)
@@ -74,95 +73,89 @@ public:
     void Reset( RESET_REASON aReason ) override;
 
     /**
-     * Function Main()
-     *
      * The main loop.
      */
     int Main( const TOOL_EVENT& aEvent );
 
     /**
-     * Function GetSelection()
+     * Return the set of currently selected items.
-     *
-     * Returns the set of currently selected items.
      */
     PCB_SELECTION& GetSelection();
 
     /**
-     * Function RequestSelection()
+     * Return the current selection set, filtered according to aFlags and aClientFilter.
      *
-     * Returns the current selection set, filtered according to aFlags and 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
-     *                            items from the selection or override the locks
+     *                            items from the selection or override the locks.
      */
     PCB_SELECTION& RequestSelection( CLIENT_SELECTION_FILTER aClientFilter,
                                      bool aConfirmLockedItems = false );
 
-    ///> Select a single item under cursor event handler.
+    ///< Select a single item under cursor event handler.
     int CursorSelection( const TOOL_EVENT& aEvent );
 
-    ///> Clear current selection event handler.
+    ///< Clear current selection event handler.
     int ClearSelection( const TOOL_EVENT& aEvent );
     void ClearSelection( bool aQuietMode = false );
 
-    ///> Item selection event handler.
+    ///< Item selection event handler.
     int SelectItem( const TOOL_EVENT& aEvent );
     void AddItemToSel( BOARD_ITEM* aItem, bool aQuietMode = false );
 
-    ///> Select all items on the board
+    ///< Select all items on the board
     int SelectAll( const TOOL_EVENT& aEvent );
 
-    ///> Multiple item selection event handler
+    ///< Multiple item selection event handler
     int SelectItems( const TOOL_EVENT& aEvent );
 
-    ///> Item unselection event handler.
+    ///< Item unselection event handler.
     int UnselectItem( const TOOL_EVENT& aEvent );
     void RemoveItemFromSel( BOARD_ITEM* aItem, bool aQuietMode = false );
 
-    ///> Multiple item unselection event handler
+    ///< Multiple item unselection event handler
     int UnselectItems( const TOOL_EVENT& aEvent );
 
     void BrightenItem( BOARD_ITEM* aItem );
     void UnbrightenItem( BOARD_ITEM* aItem );
 
     /**
-     * Function select()
+     * Take necessary action mark an item as selected.
-     * Takes necessary action mark an item as selected.
      *
      * @param aItem is an item to be selected.
      */
     void select( BOARD_ITEM* aItem );
 
     /**
-     * Function selectable()
+     * Check conditions for an item to be selected.
-     * Checks conditions for an item to be selected.
      *
      * @return True if the item fulfills conditions to be selected.
      */
     bool Selectable( const BOARD_ITEM* aItem, bool checkVisibilityOnly = false ) const;
 
     /**
-     * Function guessSelectionCandidates()
+     * Try to guess best selection candidates in case multiple items are clicked, by doing
-     * Tries 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 aWhere is the selection point to consider
      */
     void GuessSelectionCandidates( GENERAL_COLLECTOR& aCollector, const VECTOR2I& aWhere ) const;
 
     /**
-     * Function SelectionMenu()
+     * Show a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single
-     * Shows a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single
      * item.
      *
-     * NOTE: this routine DOES NOT modify the selection.
+     * @note This routine **does not** modify the selection.
      */
     int SelectionMenu( const TOOL_EVENT& aEvent );
 
     /**
-     * Rebuilds the selection from the EDA_ITEMs' selection flags.  Commonly called after
+     * Rebuild the selection from the EDA_ITEMs' selection flags.
-     * rolling back an undo state to make sure there aren't any stale pointers.
+     *
+     * Commonly called after rolling back an undo state to make sure there aren't any stale
+     * pointers.
      */
     void RebuildSelection();
 
@@ -171,10 +164,10 @@ public:
         return m_filter;
     }
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
-    ///> Zooms the screen to center and fit the current selection.
+    ///< Zoom the screen to center and fit the current selection.
     void zoomFitSelection();
 
     BOARD* GetBoard() const
@@ -195,20 +188,22 @@ public:
 
     PCB_GROUP* GetEnteredGroup() { return m_enteredGroup; }
 
-    ///> Applies the SELECTION_FILTER_OPTIONS to a collection of items
+    ///< Apply the SELECTION_FILTER_OPTIONS to a collection of items
     void FilterCollectedItems( GENERAL_COLLECTOR& aCollector );
 
 private:
 
     /**
-     * Function selectPoint()
+     * Select an item pointed by the parameter \a aWhere.
-     * Selects an item pointed by the parameter aWhere. If there is more than one item at that
+     *
-     * place, there is a menu displayed that allows one to choose the item.
+     * If there is more than one item at that place, there is a menu displayed that allows
+     * one to choose the item.
      *
      * @param aWhere is the place where the item should be selected.
      * @param aOnDrag indicates whether a drag operation is being performed.
      * @param aSelectionCancelledFlag allows the function to inform its caller that a selection
-     * was cancelled (for instance, by clicking outside of the disambiguation menu).
+     *                                was canceled (for instance, by clicking outside of the
+     *                                disambiguation menu).
      * @param aClientFilter allows the client to perform tool- or action-specific filtering.
      * @return True if an item was selected, false otherwise.
      */
@@ -217,9 +212,9 @@ private:
                       CLIENT_SELECTION_FILTER aClientFilter = NULL );
 
     /**
-     * Function selectCursor()
+     * Select an item under the cursor unless there is something already selected or
-     * Selects an item under the cursor unless there is something already selected or aSelectAlways
+     * \a aSelectAlways is true.
-     * is true.
+     *
      * @param aForceSelect forces to select an item even if there is an item already selected.
      * @param aClientFilter allows the client to perform tool- or action-specific filtering.
      * @return true if eventually there is an item selected, false otherwise.
@@ -228,99 +223,98 @@ private:
                        CLIENT_SELECTION_FILTER aClientFilter = NULL );
 
     /**
-     * Function selectMultiple()
+     * Handle drawing a selection box that allows one to select many items at the same time.
-     * Handles drawing a selection box that allows one to select many items at
-     * the same time.
      *
-     * @return true if the function was cancelled (i.e. CancelEvent was received).
+     * @return true if the function was canceled (i.e. CancelEvent was received).
      */
     bool selectMultiple();
 
     /**
-     * Allows the selection of a single item from a list via pop-up menu.  The items are
+     * Allow the selection of a single item from a list via pop-up menu.
-     * highlighted on the canvas when hovered in the menu.  The collector is trimmed to
+     *
-     * the picked item.
+     * The items are highlighted on the canvas when hovered in the menu.  The collector is
+     * trimmed to the picked item.
+     *
      * @return true if an item was picked
      */
     bool doSelectionMenu( GENERAL_COLLECTOR* aItems );
 
     /**
-     * Expands the current track selection to the next boundary (junctions, pads, or all)
+     * Expand the current track selection to the next boundary (junctions, pads, or all)
      */
     int expandConnection( const TOOL_EVENT& aEvent );
 
     /**
-     * Selects all copper connections belonging to the same net(s) as the
+     * Select all copper connections belonging to the same net(s) as the items in the selection
-     * items in the selection
      */
     int selectNet( const TOOL_EVENT& aEvent );
 
     enum STOP_CONDITION
     {
-        /** Stop at any place where more than two traces meet
+        /**
+         * Stop at any place where more than two traces meet.
          *
-         * Because vias are also traces, this makes selection stop at a
+         * Because vias are also traces, this makes selection stop at a via if there is a trace
-         * via if there is a trace on another layer as well, but a via
+         * on another layer as well, but a via with only one connection will be selected.
-         * with only one connection will be selected. */
+         */
         STOP_AT_JUNCTION,
-        /** Stop when reaching a pad */
+        /** Stop when reaching a pad. */
         STOP_AT_PAD,
-        /** Select the entire net */
+        /** Select the entire net. */
         STOP_NEVER
     };
 
     /**
-     * Selects connecteed tracks and vias.
+     * Select connected tracks and vias.
      *
      * @param aStopCondition where to stop selecting more items
      */
     void selectConnectedTracks( BOARD_CONNECTED_ITEM& aSourceItem, STOP_CONDITION aStopCondition );
 
     /**
-     * Selects all items with the given net code
+     * Select all items with the given net code.
+     *
      * @param aNetCode is the target net to select
      * @param aSelect is true to add the items to the selection, false to remove them (deselect)
      */
     void selectAllItemsOnNet( int aNetCode, bool aSelect = true );
 
     /**
-     * Selects all items with the given sheet timestamp/UUID name
+     * Select all items with the given sheet timestamp/UUID name (the sheet path).
-     * (the sheet path)
+     *
-     * The path of the root sheet is "/"
+     * The path of the root sheet is "/".
      */
     void selectAllItemsOnSheet( wxString& aSheetPath );
 
-    ///> Selects all footprints belonging to same sheet, from Eeschema,
+    ///< Select all footprints belonging to same sheet, from Eeschema using cross-probing.
-    ///> using crossprobing
     int selectSheetContents( const TOOL_EVENT& aEvent );
 
-    ///> Selects all footprints belonging to same hierarchical sheet
+    ///< Select all footprints belonging to same hierarchical sheet as the selected footprint
-    ///> as the selected footprint (same sheet path).
+    ///< (same sheet path).
     int selectSameSheet( const TOOL_EVENT& aEvent );
 
-    ///> Find dialog callback.
+    ///< Find dialog callback.
     void findCallback( BOARD_ITEM* aItem );
 
-    ///> Find an item.
+    ///< Find an item.
     int find( const TOOL_EVENT& aEvent );
 
-    ///> Invoke filter dialog and modify current selection
+    ///< Invoke filter dialog and modify current selection
     int filterSelection( const TOOL_EVENT& aEvent );
 
-    ///> Returns true if the given item passes the current SELECTION_FILTER_OPTIONS
+    ///< Return true if the given item passes the current SELECTION_FILTER_OPTIONS.
     bool itemPassesFilter( BOARD_ITEM* aItem );
 
     /**
-     * Function unselect()
+     * Take necessary action mark an item as unselected.
-     * Takes necessary action mark an item as unselected.
      *
      * @param aItem is an item to be unselected.
      */
     void unselect( BOARD_ITEM* aItem );
 
     /**
-     * Function highlight()
+     * Highlight the item visually.
-     * Highlights the item visually.
+     *
      * @param aItem is an item to be be highlighted.
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
      * @param aGroup is the group to add the item to in the BRIGHTENED mode.
@@ -328,8 +322,8 @@ private:
     void highlight( BOARD_ITEM* aItem, int aHighlightMode, PCB_SELECTION* aGroup = nullptr );
 
     /**
-     * Function unhighlight()
+     * Unhighlight the item visually.
-     * Unhighlights the item visually.
+     *
      * @param aItem is an item to be be highlighted.
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
      * @param aGroup is the group to remove the item from.
@@ -337,7 +331,6 @@ private:
     void unhighlight( BOARD_ITEM* aItem, int aHighlightMode, PCB_SELECTION* aGroup = nullptr );
 
     /**
-     * Function selectionContains()
      * @return True if the given point is contained in any of selected items' bounding box.
      */
     bool selectionContains( const VECTOR2I& aPoint ) const;

pcbnew/tools/pcb_viewer_tools.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -30,11 +30,10 @@
 class PCB_BASE_FRAME;
 
 /**
- * PCB_VIEWER_TOOLS
+ * Tool useful for viewing footprints.
  *
- * Tools useful for viewing footprints.
+ * This tool is designed to be lighter-weight so that it doesn't bring in as many PcbNew
- * This tool is designed to be lighter-weight so that it doesn't
+ * dependencies (since it is used in cvpcb).
- * bring in as many pcbnew dependencies (since it is used in cvpcb).
  */
 class PCB_VIEWER_TOOLS : public TOOL_INTERACTIVE
 {
@@ -51,7 +50,7 @@ public:
     /// @copydoc TOOL_BASE::Reset()
     void Reset( RESET_REASON aReason ) override;
 
-    ///> Launches a tool to measure between points
+    ///< Launch a tool to measure between points.
     int MeasureTool( const TOOL_EVENT& aEvent );
 
     // Display modes
@@ -64,12 +63,15 @@ public:
     /// Show the 3D viewer
     int Show3DViewer( const TOOL_EVENT& aEvent );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
     /**
-     * Toggles edit footprint mode. When enabled, one may select parts of footprints individually
+     * Toggle edit footprint mode.
-     * (graphics, pads, etc.), so they can be modified.
+     *
+     * When enabled, one may select parts of footprints individually (graphics, pads, etc.),
+     * so they can be modified.
+     *
      * @param aEnabled decides if the mode should be enabled.
      */
     void SetFootprintFrame( bool aIsFrame )
@@ -83,8 +85,6 @@ public:
     }
 
 protected:
-    bool m_footprintFrame;  ///< Is this tool associated with a footprint frame
-
     PCB_BASE_FRAME* frame() const
     {
         return getEditFrame<PCB_BASE_FRAME>();
@@ -114,6 +114,8 @@ protected:
     {
         return board()->GetFirstFootprint();
     }
+
+    bool m_footprintFrame;  ///< Is this tool associated with a footprint frame
 };
 
 #endif

pcbnew/tools/placement_tool.h

@@ -2,6 +2,8 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2014 CERN
+ * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -48,62 +50,58 @@ public:
     bool Init() override;
 
     /**
-     * Function AlignTop()
+     * Set Y coordinate of the selected items to the value of the top-most selected item Y
-     * Sets Y coordinate of the selected items to the value of the top-most selected item Y coordinate.
+     * coordinate.
      */
     int AlignTop( const TOOL_EVENT& aEvent );
 
     /**
-     * Function AlignBottom()
+     * Sets Y coordinate of the selected items to the value of the bottom-most selected item Y
-     * Sets Y coordinate of the selected items to the value of the bottom-most selected item Y coordinate.
+     * coordinate.
      */
     int AlignBottom( const TOOL_EVENT& aEvent );
 
     /**
-     * Function AlignLeft()
+     * Sets X coordinate of the selected items to the value of the left-most selected item X
-     * Sets X coordinate of the selected items to the value of the left-most selected item X coordinate.
+     * coordinate.
      */
     int AlignLeft( const TOOL_EVENT& aEvent );
 
     /**
-     * Function AlignRight()
+     * Sets X coordinate of the selected items to the value of the right-most selected item X
-     * Sets X coordinate of the selected items to the value of the right-most selected item X coordinate.
+     * coordinate.
      */
     int AlignRight( const TOOL_EVENT& aEvent );
 
     /**
-     * Function AlignCenterX()
+     * Set the x coordinate of the midpoint of each of the selected items to the value of the
-     * Sets the x coordinate of the midpoint of each of the selected items to
+     * x coordinate of the center of the middle selected item.
-     * the value of the x coordinate of the center of the middle selected item.
      */
     int AlignCenterX( const TOOL_EVENT& aEvent );
 
     /**
-     * Function AlignCenterX()
+     * Set the y coordinate of the midpoint of each of the selected items to the value of the
-     * Sets the y coordinate of the midpoint of each of the selected items to
+     * y coordinate of the center of the middle selected item.
-     * the value of the y coordinate of the center of the middle selected item.
      */
     int AlignCenterY( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DistributeHorizontally()
+     * Distribute the selected items along the X axis.
-     * Distributes the selected items along the X axis.
      */
     int DistributeHorizontally( const TOOL_EVENT& aEvent );
 
     /**
-     * Function DistributeVertically()
+     * Distribute the selected items along the Y axis.
-     * Distributes the selected items along the Y axis.
      */
     int DistributeVertically( const TOOL_EVENT& aEvent );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:
     /**
-     * Function GetSelections()
+     * Populate two vectors with the sorted selection and sorted locked items.
-     * Populates two vectors with the sorted selection and sorted locked items
+     *
      * Returns the size of aItemsToAlign()
      */
     template< typename T >
@@ -114,35 +112,40 @@ private:
     int selectTarget( ALIGNMENT_RECTS& aItems, ALIGNMENT_RECTS& aLocked, T aGetValue );
 
     /**
-     * Sets X coordinate of the selected items to the value of the left-most selected item X coordinate.
+     * Sets X coordinate of the selected items to the value of the left-most selected item
+     * X coordinate.
      *
-     * NOTE: Uses the bounding box of items, which do not get mirrored even when
+     * @note Uses the bounding box of items, which do not get mirrored even when
      *       the view is mirrored!
      */
     int doAlignLeft();
 
     /**
-     * Aligns selected items using the right edge of their bounding boxes to the right-most item
+     * Align selected items using the right edge of their bounding boxes to the right-most item.
      *
-     * NOTE: Uses the bounding box of items, which do not get mirrored even when
+     * @note Uses the bounding box of items, which do not get mirrored even when
      *       the view is mirrored!
      */
     int doAlignRight();
 
     /**
-     * Distributes selected items using an even spacing between the centers of their bounding boxes
+     * Distribute selected items using an even spacing between the centers of their bounding
+     * boxes.
      *
-     * NOTE: Using the centers of bounding box of items can give unsatisfactory visual results since
+     * @note Using the centers of bounding box of items can give unsatisfactory visual results
-     * items of differing widths will be placed with different gaps. Is only used if items overlap
+     * since items of differing widths will be placed with different gaps. Is only used if
+     * items overlap.
      */
     void doDistributeCentersHorizontally( ALIGNMENT_RECTS& itemsToDistribute,
                                           BOARD_COMMIT& aCommit ) const;
 
     /**
-     * Distributes selected items using an even spacing between the centers of their bounding boxes
+     * Distribute selected items using an even spacing between the centers of their bounding
+     * boxes.
      *
-     * NOTE: Using the centers of bounding box of items can give unsatisfactory visual results since
+     * @note Using the centers of bounding box of items can give unsatisfactory visual results
-     * items of differing widths will be placed with different gaps. Is only used if items overlap
+     *       since items of differing widths will be placed with different gaps. Is only used
+     *       if items overlap
      */
     void doDistributeCentersVertically( ALIGNMENT_RECTS& itemsToDistribute,
                                         BOARD_COMMIT& aCommit ) const;
@@ -150,7 +153,7 @@ private:
     /**
      * Distributes selected items using an even spacing between their bounding boxes
      *
-     * NOTE: Using the edges of bounding box of items is only possible if there is enough space
+     * @note Using the edges of bounding box of items is only possible if there is enough space
      *       between them. If this is not the case, use the center spacing method
      */
     void doDistributeGapsHorizontally( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit,
@@ -159,7 +162,7 @@ private:
     /**
      * Distributes selected items using an even spacing between their bounding boxes
      *
-     * NOTE: Using the edges of bounding box of items is only possible if there is enough space
+     * @note Using the edges of bounding box of items is only possible if there is enough space
      *       between them. If this is not the case, use the center spacing method
      */
     void doDistributeGapsVertically( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit,

pcbnew/tools/position_relative_tool.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -36,10 +36,10 @@ class PCB_SELECTION_TOOL;
 class DIALOG_POSITION_RELATIVE;
 
 /**
- * POSITION_RELATIVE_TOOL
+ * The interactive edit tool.
  *
- * The interactive edit tool. Allows one to move, rotate, flip and change properties of items selected
+ * Allows one to move, rotate, flip and change properties of items selected using the
- * using the pcbnew.InteractiveSelection tool.
+ * pcbnew.InteractiveSelection tool.
  */
 
 class POSITION_RELATIVE_TOOL : public PCB_TOOL_BASE
@@ -53,37 +53,28 @@ public:
     bool Init() override;
 
     /**
-     * Function PositionRelative()
+     * Invoke a dialog box to allow positioning of the item relative to another by an exact amount.
-     *
-     * Invokes a dialog box to allow positioning of the item relative to another by an exact amount.
      */
     int PositionRelative( const TOOL_EVENT& aEvent );
 
     /**
-     * Function SelectPositionRelativeItem()
+     * Invoke the picker tool to select the item to which the previous selection will be placed
-     *
-     * Invokes the picker tool to select the item to which the previous selection will be placed
      * relative to.
      */
     int SelectPositionRelativeItem( const TOOL_EVENT& aEvent  );
 
     /**
-     * Function GetSelectionAnchorPosition()
+     * Return the position of the selected item(s)
-     *
-     * Returns the postion of the selected item(s)
-     *
      */
     wxPoint GetSelectionAnchorPosition() const { return m_selectionAnchor; }
 
     /**
-     * Function RelativeItemSelectionMove()
+     * Position the m_position_relative_selection selection relative to anchor position using
-     *
-     * Positions the m_position_relative_selection selection relative to anchorpostion using
      * the given translation.
      */
     int RelativeItemSelectionMove( wxPoint anchor, wxPoint translation );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 
 private:

pcbnew/tools/zone_create_helper.h

@@ -1,7 +1,7 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2017-2019 Kicad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -35,38 +35,37 @@ class VIEW;
 }
 
 /**
- * This class is an adjuct helper to the DRAWING_TOOL interactive tool, which handles incoming
+ * An adjunct helper to the DRAWING_TOOL interactive tool, which handles incoming geometry
- * geometry changes from a POLYGON_GEOM_MANAGER and translates that into a ZONE based on given
+ * changes from a #POLYGON_GEOM_MANAGER and translates that into a ZONE based on given
- * parameters
+ * parameters.
  */
 class ZONE_CREATE_HELPER : public POLYGON_GEOM_MANAGER::CLIENT
 {
 public:
-
     /**
      * Parameters used to fully describe a zone creation process
      */
     struct PARAMS
     {
-        ///> Should create a keepout zone?
+        ///< Should create a keepout zone?
         bool m_keepout;
 
-        ///> Layer to begin drawing
+        ///< Layer to begin drawing
         PCB_LAYER_ID m_layer;
 
-        ///> The zone mode to operate in
+        ///< The zone mode to operate in
         ZONE_MODE m_mode;
 
-        ///> Zone settings source (for similar and cutout zones)
+        ///< Zone settings source (for similar and cutout zones)
         ZONE* m_sourceZone;
 
-        ///> Zone leader mode
+        ///< Zone leader mode
         POLYGON_GEOM_MANAGER::LEADER_MODE m_leaderMode;
     };
 
     /**
-     * @param aTool the DRAWING_TOOL to provide the zone tool to
+     * @param aTool the #DRAWING_TOOL to provide the zone tool to.
-     * @param aParams the parameters to use to guide the zone creation
+     * @param aParams the parameters to use to guide the zone creation.
      */
     ZONE_CREATE_HELPER( DRAWING_TOOL& aTool, PARAMS& aParams );
 
@@ -75,9 +74,8 @@ public:
     ZONE* GetZone() const { return m_zone.get(); }
 
     /*
-     * Interface for receiving POLYGON_GEOM_MANAGER update
+     * Interface for receiving #POLYGON_GEOM_MANAGER update
      */
-
     void OnGeometryChange( const POLYGON_GEOM_MANAGER& aMgr ) override;
 
     bool OnFirstPoint( POLYGON_GEOM_MANAGER& aMgr ) override;
@@ -85,10 +83,7 @@ public:
     void OnComplete( const POLYGON_GEOM_MANAGER& aMgr ) override;
 
     /**
-     * Function createNewZone()
+     * Prompt the user for new zone settings, and create a new zone with those settings.
-     *
-     * Prompt the user for new zone settings, and create a new zone with
-     * those settings
      *
      * @param aKeepout should the zone be a keepout
      * @return the new zone, can be null if the user aborted
@@ -96,9 +91,7 @@ public:
     std::unique_ptr<ZONE> createNewZone( bool aKeepout );
 
     /**
-     * Function createZoneFromExisting
+     * Create a new zone with the settings from an existing zone.
-     *
-     * Create a new zone with the settings from an existing zone
      *
      * @param aSrcZone the zone to copy settings from
      * @return the new zone
@@ -106,10 +99,7 @@ public:
     std::unique_ptr<ZONE> createZoneFromExisting( const ZONE& aSrcZone );
 
     /**
-     * Function performZoneCutout()
+     * Cut one zone out of another one (i.e. subtraction) and update the zone..
-     *
-     * Cut one zone out of another one (i.e. subtraction) and
-     * update the zone.
      *
      * @param aZone the zone to removed area from
      * @param aCutout the area to remove
@@ -117,28 +107,28 @@ public:
     void performZoneCutout( ZONE& aZone, ZONE& aCutout );
 
     /**
-     * Commit the current zone-in-progress to the BOARD. This might
+     * Commit the current zone-in-progress to the BOARD.
-     * be adding a new zone, or modifying an existing zone with a
-     * cutout, depending on parameters.
      *
-     * @param aZone - the drawn zone outline to commit
+     * This might be adding a new zone, or modifying an existing zone with a cutout, depending
+     * on parameters.
+     *
+     * @param aZone is the drawn zone outline to commit.
      */
     void commitZone( std::unique_ptr<ZONE> aZone );
 
 private:
-
     DRAWING_TOOL& m_tool;
 
-    ///> Parameters of the zone to be drawn
+    ///< Parameters of the zone to be drawn
     PARAMS& m_params;
 
-    ///> The preview item to display
+    ///< The preview item to display
     KIGFX::PREVIEW::POLYGON_ITEM m_previewItem;
 
-    ///> view that show the preview item
+    ///< view that show the preview item
     KIGFX::VIEW& m_parentView;
 
-    ///> The zone-in-progress
+    ///< The zone-in-progress
     std::unique_ptr<ZONE> m_zone;
 };
 

pcbnew/tools/zone_filler_tool.h

@@ -1,7 +1,9 @@
 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
- * Copyright (C) 2014 - 2017 CERN
+ * Copyright (C) 2014 CERN
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
+ *
  * @author Maciej Suminski <maciej.suminski@cern.ch>
  *
  * This program is free software; you can redistribute it and/or
@@ -33,9 +35,7 @@ class WX_PROGRESS_REPORTER;
 
 
 /**
- * ZONE_FILLER_TOOL
+ * Handle actions specific to filling copper zones.
- *
- * Handles actions specific to filling copper zones.
  */
 class ZONE_FILLER_TOOL : public PCB_TOOL_BASE
 {
@@ -55,10 +55,10 @@ public:
     int ZoneUnfillAll( const TOOL_EVENT& aEvent );
 
 private:
-    ///> Refocuses on an idle event (used after the Progress Reporter messes up the focus)
+    ///< Refocus on an idle event (used after the Progress Reporter messes up the focus).
     void singleShotRefocus( wxIdleEvent& );
 
-    ///> Sets up handlers for various events.
+    ///< Set up handlers for various events.
     void setTransitions() override;
 };
 

pcbnew/widgets/appearance_controls.h

@@ -2,7 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2020 Jon Evans <jon@craftyjon.com>
- * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
+ * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -201,7 +201,7 @@ public:
 
     wxSize GetBestSize() const;
 
-    ///> Updates the panel contents from the application and board models
+    ///< Update the panel contents from the application and board models.
     void OnBoardChanged();
 
     void OnBoardNetSettingsChanged( BOARD& aBoard ) override;
@@ -218,26 +218,26 @@ public:
 
     void OnBoardItemsChanged( BOARD& aBoard, std::vector<BOARD_ITEM*>& aBoardItems ) override;
 
-    ///> Updates the colors on all the widgets from the new chosen color theme
+    ///< Update the colors on all the widgets from the new chosen color theme.
     void OnColorThemeChanged();
 
-    ///> Updates the widget when the active board layer is changed
+    ///< Update the widget when the active board layer is changed.
     void OnLayerChanged();
 
-    ///> Manually update visibility for a given layer
+    ///< Manually update visibility for a given layer
     void SetLayerVisible( LAYER_NUM aLayer, bool isVisible );
 
     void SetObjectVisible( GAL_LAYER_ID aLayer, bool isVisible = true );
 
-    ///> Updates the manual layer alpha overrides
+    ///< Update the manual layer alpha overrides.
     void OnLayerAlphaChanged();
 
     void UpdateDisplayOptions();
 
-    ///> Returns a list of the layer presets created by the user
+    ///< Return a list of the layer presets created by the user.
     std::vector<LAYER_PRESET> GetUserLayerPresets() const;
 
-    ///> Updates the current layer presets from those saved in the project file
+    ///< Update the current layer presets from those saved in the project file.
     void SetUserLayerPresets( std::vector<LAYER_PRESET>& aPresetList );
 
     void ApplyLayerPreset( const wxString& aPresetName );
@@ -261,14 +261,13 @@ public:
 
     void OnLayerContextMenu( wxCommandEvent& aEvent );
 
-    ///> Returns the index of the current tab (0-2)
+    ///< Return the index of the current tab (0-2).
     int GetTabIndex() const;
 
-    ///> Sets the current notebook tab
+    ///< Set the current notebook tab.
     void SetTabIndex( int aTab );
 
 protected:
-
     void OnNotebookPageChanged( wxNotebookEvent& event ) override;
 
     void OnSetFocus( wxFocusEvent& aEvent ) override;
@@ -284,122 +283,6 @@ protected:
     void OnNetGridMouseEvent( wxMouseEvent& aEvent );
 
 private:
-    PCB_BASE_FRAME* m_frame;
-
-    wxWindow* m_focusOwner;
-
-    static const APPEARANCE_SETTING s_objectSettings[];
-
-    ROW_ICON_PROVIDER* m_iconProvider;
-
-    BOARD* m_board;
-
-    bool m_isFpEditor;
-
-    // Nets grid view
-    NET_GRID_TABLE* m_netsTable;
-
-    GRID_BITMAP_TOGGLE_RENDERER* m_toggleGridRenderer;
-
-    /// Grid cell that is being hovered over, for tooltips
-    wxGridCellCoords m_hoveredCell;
-
-    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_layerSettings;
-
-    std::map<PCB_LAYER_ID, APPEARANCE_SETTING*> m_layerSettingsMap;
-
-    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_objectSettings;
-
-    std::map<GAL_LAYER_ID, APPEARANCE_SETTING*> m_objectSettingsMap;
-
-    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_netclassSettings;
-
-    std::map<wxString, APPEARANCE_SETTING*> m_netclassSettingsMap;
-
-    // TODO(JE) Move preset storage to the PCB_CONTROL tool
-
-    // Storage for all layer presets
-    std::map<wxString, LAYER_PRESET> m_layerPresets;
-
-    LAYER_PRESET* m_currentPreset;
-
-    /// The last user (non-read-only) preset selected by the user
-    LAYER_PRESET* m_lastSelectedUserPreset;
-
-    wxArrayString m_presetMRU;
-
-    wxMenu* m_layerContextMenu;
-
-    /// Stores wxIDs for each netclass for control event mapping
-    std::map<int, wxString> m_netclassIdMap;
-
-    /// The name of the netclass that was right-clicked
-    wxString m_contextMenuNetclass;
-
-    wxBoxSizer* m_layersOuterSizer;
-    wxBoxSizer* m_objectsOuterSizer;
-
-    // The built-in layer presets
-
-    static LAYER_PRESET presetNoLayers;
-    static LAYER_PRESET presetAllLayers;
-    static LAYER_PRESET presetAllCopper;
-    static LAYER_PRESET presetInnerCopper;
-    static LAYER_PRESET presetFront;
-    static LAYER_PRESET presetFrontAssembly;
-    static LAYER_PRESET presetBack;
-    static LAYER_PRESET presetBackAssembly;
-
-    int m_pointSize;
-
-    wxColour m_layerPanelColour;
-
-    // Layer display options controls
-
-    WX_COLLAPSIBLE_PANE* m_paneLayerDisplayOptions;
-    wxStaticText*        m_staticTextContrastModeTitle;
-    wxRadioButton*       m_rbHighContrastNormal;
-    wxRadioButton*       m_rbHighContrastDim;
-    wxRadioButton*       m_rbHighContrastOff;
-    wxStaticLine*        m_layerDisplaySeparator;
-    wxCheckBox*          m_cbFlipBoard;
-
-    // Net display options controls
-
-    WX_COLLAPSIBLE_PANE* m_paneNetDisplayOptions;
-    wxStaticText*        m_txtNetDisplayTitle;
-    wxRadioButton*       m_rbNetColorAll;
-    wxRadioButton*       m_rbNetColorRatsnest;
-    wxRadioButton*       m_rbNetColorOff;
-    wxStaticText*        m_txtRatsnestVisibility;
-    wxRadioButton*       m_rbRatsnestAllLayers;
-    wxRadioButton*       m_rbRatsnestVisibleLayers;
-
-    enum POPUP_ID
-    {
-        ID_CHANGE_COLOR = wxID_HIGHEST,
-        ID_SET_NET_COLOR,
-        ID_CLEAR_NET_COLOR,
-        ID_SHOW_ALL_NETS,
-        ID_HIDE_OTHER_NETS,
-        ID_HIGHLIGHT_NET,
-        ID_SELECT_NET,
-        ID_DESELECT_NET,
-        ID_SHOW_ALL_COPPER_LAYERS,
-        ID_HIDE_ALL_COPPER_LAYERS,
-        ID_HIDE_ALL_BUT_ACTIVE,
-        ID_PRESET_NO_LAYERS,
-        ID_PRESET_ALL_LAYERS,
-        ID_PRESET_FRONT,
-        ID_PRESET_FRONT_ASSEMBLY,
-        ID_PRESET_INNER_COPPER,
-        ID_PRESET_BACK,
-        ID_PRESET_BACK_ASSEMBLY,
-        ID_HIDE_ALL_NON_COPPER,
-        ID_SHOW_ALL_NON_COPPER,
-        ID_LAST_VALUE
-    };
-
     void createControls();
 
     void rebuildLayers();
@@ -469,6 +352,119 @@ private:
     bool doesBoardItemNeedRebuild( BOARD_ITEM* aBoardItem );
 
     bool doesBoardItemNeedRebuild( std::vector<BOARD_ITEM*>& aBoardItems );
+
+    PCB_BASE_FRAME* m_frame;
+
+    wxWindow* m_focusOwner;
+
+    static const APPEARANCE_SETTING s_objectSettings[];
+
+    ROW_ICON_PROVIDER* m_iconProvider;
+
+    BOARD* m_board;
+
+    bool m_isFpEditor;
+
+    // Nets grid view
+    NET_GRID_TABLE* m_netsTable;
+
+    GRID_BITMAP_TOGGLE_RENDERER* m_toggleGridRenderer;
+
+    /// Grid cell that is being hovered over, for tooltips
+    wxGridCellCoords m_hoveredCell;
+
+    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_layerSettings;
+
+    std::map<PCB_LAYER_ID, APPEARANCE_SETTING*> m_layerSettingsMap;
+
+    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_objectSettings;
+
+    std::map<GAL_LAYER_ID, APPEARANCE_SETTING*> m_objectSettingsMap;
+
+    std::vector<std::unique_ptr<APPEARANCE_SETTING>> m_netclassSettings;
+
+    std::map<wxString, APPEARANCE_SETTING*> m_netclassSettingsMap;
+
+    // TODO(JE) Move preset storage to the PCB_CONTROL tool
+
+    // Storage for all layer presets
+    std::map<wxString, LAYER_PRESET> m_layerPresets;
+
+    LAYER_PRESET* m_currentPreset;
+
+    /// The last user (non-read-only) preset selected by the user
+    LAYER_PRESET* m_lastSelectedUserPreset;
+
+    wxArrayString m_presetMRU;
+
+    wxMenu* m_layerContextMenu;
+
+    /// Stores wxIDs for each netclass for control event mapping
+    std::map<int, wxString> m_netclassIdMap;
+
+    /// The name of the netclass that was right-clicked
+    wxString m_contextMenuNetclass;
+
+    wxBoxSizer* m_layersOuterSizer;
+    wxBoxSizer* m_objectsOuterSizer;
+
+    // The built-in layer presets
+    static LAYER_PRESET presetNoLayers;
+    static LAYER_PRESET presetAllLayers;
+    static LAYER_PRESET presetAllCopper;
+    static LAYER_PRESET presetInnerCopper;
+    static LAYER_PRESET presetFront;
+    static LAYER_PRESET presetFrontAssembly;
+    static LAYER_PRESET presetBack;
+    static LAYER_PRESET presetBackAssembly;
+
+    int m_pointSize;
+
+    wxColour m_layerPanelColour;
+
+    // Layer display options controls
+    WX_COLLAPSIBLE_PANE* m_paneLayerDisplayOptions;
+    wxStaticText*        m_staticTextContrastModeTitle;
+    wxRadioButton*       m_rbHighContrastNormal;
+    wxRadioButton*       m_rbHighContrastDim;
+    wxRadioButton*       m_rbHighContrastOff;
+    wxStaticLine*        m_layerDisplaySeparator;
+    wxCheckBox*          m_cbFlipBoard;
+
+    // Net display options controls
+    WX_COLLAPSIBLE_PANE* m_paneNetDisplayOptions;
+    wxStaticText*        m_txtNetDisplayTitle;
+    wxRadioButton*       m_rbNetColorAll;
+    wxRadioButton*       m_rbNetColorRatsnest;
+    wxRadioButton*       m_rbNetColorOff;
+    wxStaticText*        m_txtRatsnestVisibility;
+    wxRadioButton*       m_rbRatsnestAllLayers;
+    wxRadioButton*       m_rbRatsnestVisibleLayers;
+
+    enum POPUP_ID
+    {
+        ID_CHANGE_COLOR = wxID_HIGHEST,
+        ID_SET_NET_COLOR,
+        ID_CLEAR_NET_COLOR,
+        ID_SHOW_ALL_NETS,
+        ID_HIDE_OTHER_NETS,
+        ID_HIGHLIGHT_NET,
+        ID_SELECT_NET,
+        ID_DESELECT_NET,
+        ID_SHOW_ALL_COPPER_LAYERS,
+        ID_HIDE_ALL_COPPER_LAYERS,
+        ID_HIDE_ALL_BUT_ACTIVE,
+        ID_PRESET_NO_LAYERS,
+        ID_PRESET_ALL_LAYERS,
+        ID_PRESET_FRONT,
+        ID_PRESET_FRONT_ASSEMBLY,
+        ID_PRESET_INNER_COPPER,
+        ID_PRESET_BACK,
+        ID_PRESET_BACK_ASSEMBLY,
+        ID_HIDE_ALL_NON_COPPER,
+        ID_SHOW_ALL_NON_COPPER,
+        ID_LAST_VALUE
+    };
 };
 
 #endif

utils/kicad2step/panel_kicad2step.h

@@ -2,6 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2016
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -23,7 +24,7 @@
 
 /**
  * @file panel_kicad2step.h
- * declares the main PCB object
+ * Declare the main PCB object.
  */
 
 #ifndef PANEL_KICAD2STEP_H
@@ -38,10 +39,9 @@ class KICAD2MCAD_PRMS       // A small class to handle parameters of conversion
 public:
     KICAD2MCAD_PRMS();
 
-    ///> Returns file extension for the selected output format
+    ///< Return file extension for the selected output format
     wxString getOutputExt() const;
 
-public:
 #ifdef SUPPORTS_IGES
     bool     m_fmtIGES;
 #endif
@@ -61,14 +61,17 @@ class PANEL_KICAD2STEP: public wxPanel
 {
 public:
 	PANEL_KICAD2STEP( wxWindow* parent, wxWindowID id = wxID_ANY,
-                      const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize( 500,300 ),
+                      const wxPoint& pos = wxDefaultPosition,
+                      const wxSize& size = wxSize( 500,300 ),
                       long style = wxTAB_TRAVERSAL );
 
-    /** Run the Kicad to STEP converter
+    /**
+     * Run the KiCad to STEP converter.
      */
     int RunConverter();
 
-    /** Add a message to m_tcMessages
+    /**
+     * Add a message to m_tcMessages.
      */
     void AppendMessage( const wxString& aMessage );
 

utils/kicad2step/pcb/base.h

@@ -2,6 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2016 Cirilo Bernardo <cirilo.bernardo@gmail.com>
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -23,8 +24,7 @@
 
 /**
  * @file base.h
- * provides declarations of items which are basic to all
+ * Provide declarations of items which are basic to all kicad2mcad code.
- * kicad2mcad code.
  */
 
 #ifndef KICADBASE_H
@@ -34,7 +34,7 @@
 
 #include <ostream>
 
-///> Default minimum distance between points to treat them as separate ones (mm)
+///< Default minimum distance between points to treat them as separate ones (mm)
 static constexpr double MIN_DISTANCE = 0.01;
 
 namespace SEXPR
@@ -53,9 +53,9 @@ enum CURVE_TYPE
 
 /*
  * Layers of importance to MCAD export:
- * LAYER_TOP: specifies that a footprint is on the top of the PCB
+ *  - LAYER_TOP: specifies that a footprint is on the top of the PCB
- * LAYER_BOTTOM: specifies that a footprint is on the bottom of the PCB
+ *  - LAYER_BOTTOM: specifies that a footprint is on the bottom of the PCB
- * LAYER_EDGE: specifies that a Curve is associated with the PCB edge
+ *  - LAYER_EDGE: specifies that a Curve is associated with the PCB edge
  */
 enum LAYERS
 {
@@ -99,13 +99,12 @@ bool Get3DCoordinate( const SEXPR::SEXPR* data, TRIPLET& aCoordinate );
 bool GetXYZRotation( const SEXPR::SEXPR* data, TRIPLET& aRotation );
 
 /**
- * Get the layer name from a layer element, if the layer is syntactically
+ * Get the layer name from a layer element, if the layer is syntactically valid.
- * valid.
  *
  * E.g. (layer "Edge.Cuts") -> "Edge.Cuts"
  *
- * @param  aLayerElem the s-expr element to get the name from
+ * @param aLayerElem the s-expr element to get the name from.
- * @return            the layer name if valid, else empty
+ * @return the layer name if valid, else empty.
  */
 OPT<std::string> GetLayerName( const SEXPR::SEXPR& aLayerElem );
 

utils/kicad2step/pcb/kicadcurve.h

@@ -2,6 +2,7 @@
  * This program source code file is part of KiCad, a free EDA CAD application.
  *
  * Copyright (C) 2016 Cirilo Bernardo <cirilo.bernardo@gmail.com>
+ * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -23,7 +24,7 @@
 
 /**
  * @file kicadcurve.h
- * declares the Curve (glyph) object.
+ * Declare the Curve (glyph) object.
  */
 
 #ifndef KICADCURVE_H
@@ -47,7 +48,7 @@ public:
         return m_layer;
     }
 
-    ///> Returns human-readable description of the curve.
+    ///< Return human-readable description of the curve.
     std::string Describe() const;
 
     CURVE_TYPE m_form;          // form of curve: line, arc, circle