Housekeeping in include path sub-folders.

include/api/api_plugin.h

@@ -137,7 +137,8 @@ private:
  */
 struct CompareApiPluginIdentifiers
 {
-    bool operator()( const std::unique_ptr<API_PLUGIN>& item1, const std::unique_ptr<API_PLUGIN>& item2 ) const
+    bool operator()( const std::unique_ptr<API_PLUGIN>& item1,
+                     const std::unique_ptr<API_PLUGIN>& item2 ) const
     {
         return item1->Identifier() < item2->Identifier();
     }

include/cli/exit_codes.h

@@ -32,7 +32,8 @@ namespace CLI
         static const int ERR_UNKNOWN = 2;
         static const int ERR_INVALID_INPUT_FILE = 3;
         static const int ERR_INVALID_OUTPUT_CONFLICT = 4;
-        ///< Rules check violation count was greater than 0
+
+        /// Rules check violation count was greater than 0.
         static const int ERR_RC_VIOLATIONS = 5;
         static const int ERR_JOBS_RUN_FAILED = 6;
     };

include/dialogs/dialog_image_editor.h

@@ -44,8 +44,7 @@ public:
 
 public:
     /**
-     * Function TransferToImage
+     * Copy edited image to \a aItem.
-     * copy edited image to aItem
      */
     void TransferToImage( BITMAP_BASE* aItem );
 

include/dialogs/dialog_plugin_options.h

@@ -23,17 +23,16 @@
 
 #include <dialog_plugin_options_base.h>
 #include <core/utf8.h>
+
 /**
- * DIALOG_PLUGIN_OPTIONS
+ * An options editor in the form of a two column name/value spreadsheet like (table) UI.
- * is an options editor in the form of a two column name/value
- * spreadsheet like (table) UI.
  */
 class DIALOG_PLUGIN_OPTIONS : public DIALOG_PLUGIN_OPTIONS_BASE
 {
 public:
     DIALOG_PLUGIN_OPTIONS( wxWindow* aParent, const wxString& aNickname,
-                           const std::map<std::string, UTF8>& aPluginOptions, const wxString& aFormattedOptions,
+                           const std::map<std::string, UTF8>& aPluginOptions,
-                           wxString* aResult );
+                           const wxString& aFormattedOptions, wxString* aResult );
 
     ~DIALOG_PLUGIN_OPTIONS() override;
 

include/dialogs/dialog_unit_entry.h

@@ -39,7 +39,7 @@ public:
                           long long int aDefaultValue );
 
     /**
-     * Returns the value in internal units
+     * Return the value in internal units.
      */
     int GetValue();
 
@@ -55,7 +55,7 @@ public:
                         const wxString& aLabelY, const VECTOR2I& aDefaultValue );
 
     /**
-     * Returns the value in internal units
+     * Return the value in internal units.
      */
     VECTOR2I GetValue();
 

include/dialogs/panel_image_editor.h

@@ -41,8 +41,7 @@ public:
     bool TransferDataFromWindow() override;
 
     /**
-     * Function TransferToImage
+     * Copy edited image to \a aItem.
-     * copy edited image to aItem
      */
     void TransferToImage( BITMAP_BASE& aItem );
 

include/dialogs/panel_setup_netclasses.h

@@ -39,7 +39,7 @@ public:
     PANEL_SETUP_NETCLASSES( wxWindow* aParentWindow, EDA_DRAW_FRAME* aFrame,
                             std::shared_ptr<NET_SETTINGS> aSettings,
                             const std::set<wxString>& aNetNames, bool isEEschema );
-    ~PANEL_SETUP_NETCLASSES( ) override;
+    ~PANEL_SETUP_NETCLASSES() override;
 
     bool TransferDataToWindow() override;
     bool TransferDataFromWindow() override;

include/dialogs/panel_setup_severities.h

@@ -36,20 +36,10 @@ class wxRadioButton;
 
 class PANEL_SETUP_SEVERITIES : public wxPanel
 {
-private:
-    std::map<int, SEVERITY>& m_severities;
-
-    /// A list of item templates (to get descriptive text and error codes from)
-    std::vector<std::reference_wrapper<RC_ITEM>> m_items;
-
-    /// For ERC settings; a pointer to ERC_ITEM::pinTableConflict
-    RC_ITEM* m_pinMapSpecialCase;
-
-    std::map<int, wxRadioButton*[4]> m_buttonMap;   // map from DRC error code to button group
-
 public:
     /**
-     * Creates the severities setup panel
+     * Create the severities setup panel.
+     *
      * @param aItems is a list of error types that can have a severity.  Must have one or more!
      * @param aSeverities is a map of error code to severity
      * @param aPinMapSpecialCase is used to special-case the ERCE_PIN_TO_PIN_WARNING
@@ -68,7 +58,17 @@ private:
     void checkReload();
 
 private:
+    std::map<int, SEVERITY>& m_severities;
+
+    /// A list of item templates (to get descriptive text and error codes from)
+    std::vector<std::reference_wrapper<RC_ITEM>> m_items;
+
+    /// For ERC settings; a pointer to ERC_ITEM::pinTableConflict
+    RC_ITEM* m_pinMapSpecialCase;
+
+    std::map<int, wxRadioButton*[4]> m_buttonMap;   // map from DRC error code to button group
+
     std::map<int, SEVERITY> m_lastLoaded;
 };
 
-#endif //KICAD_PANEL_SETUP_SEVERITIES_H
+#endif // KICAD_PANEL_SETUP_SEVERITIES_H

include/drawing_sheet/ds_data_model.h

@@ -46,7 +46,7 @@ public:
     }
 
     /**
-     * static function: returns the instance of DS_DATA_MODEL used in the application
+     * Return the instance of DS_DATA_MODEL used in the application.
      */
     static DS_DATA_MODEL& GetTheInstance();
 
@@ -143,7 +143,7 @@ public:
     static wxString DefaultLayout();
 
     /**
-     * Populates the list with a custom layout or the default layout if no custom layout
+     * Populate the list with a custom layout or the default layout if no custom layout
      * is  available.
      *
      * @param aFullFileName is the custom drawing sheet file. If empty, load the file defined by

include/drawing_sheet/ds_proxy_view_item.h

@@ -67,12 +67,12 @@ public:
     void SetSheetPath( const std::string& aSheetPath ) { m_sheetPath = aSheetPath; }
 
     /**
-     * Changes the page number displayed in the title block.
+     * Change the page number displayed in the title block.
      */
     void SetPageNumber( const std::string& aPageNumber ) { m_pageNumber = aPageNumber; }
 
     /**
-     * Changes the sheet-count number displayed in the title block.
+     * Change the sheet-count number displayed in the title block.
      */
     void SetSheetCount( int aSheetCount ) { m_sheetCount = aSheetCount; }
 
@@ -91,7 +91,8 @@ public:
     void SetColorLayer( int aLayerId ) { m_colorLayer = aLayerId; }
 
     /**
-     * Overrides the layer used to pick the color of the page border (normally LAYER_GRID)
+     * Override the layer used to pick the color of the page border (normally LAYER_GRID)
+     *
      * @param aLayerId is the layer to use
      */
     void SetPageBorderColorLayer( int aLayerId ) { m_pageBorderColorLayer = aLayerId; }
@@ -113,7 +114,9 @@ public:
     void Show( int x, std::ostream& st ) const override { }
 #endif
 
-    /** Get class name
+    /**
+     * Get class name.
+     *
      * @return  string "DS_PROXY_VIEW_ITEM"
      */
     virtual wxString GetClass() const override
@@ -142,7 +145,10 @@ protected:
 
     const std::map<wxString, wxString>* m_properties;
 
-    /// Layer that is used for drawing sheet color (LAYER_DRAWINGSHEET is always used for visibility)
+    /**
+     * Layer that is used for drawing sheet color (LAYER_DRAWINGSHEET is always used
+     * for visibility).
+     */
     int                 m_colorLayer;
 
     /// Layer that is used for page border color

include/font/font.h

@@ -211,7 +211,7 @@ public:
 
 protected:
     /**
-     * Returns number of lines for a given text.
+     * Return number of lines for a given text.
      *
      * @param aText is the text to be checked.
      * @return unsigned - The number of lines in aText.
@@ -226,7 +226,7 @@ protected:
     }
 
     /**
-     * Draws a single line of text. Multiline texts should be split before using the
+     * Draw a single line of text. Multiline texts should be split before using the
      * function.
      *
      * @param aGal is a pointer to the graphics abstraction layer, or nullptr (nothing is drawn)
@@ -245,7 +245,8 @@ protected:
                              bool aItalic, bool aUnderline, const METRICS& aFontMetrics ) const;
 
     /**
-     * Computes the bounding box for a single line of text.
+     * Compute the bounding box for a single line of text.
+     *
      * Multiline texts should be split before using the function.
      *
      * @param aBBox is an optional pointer to be filled with the bounding box.
@@ -255,7 +256,8 @@ protected:
      * @return new cursor position
      */
     VECTOR2I boundingBoxSingleLine( BOX2I* aBBox, const wxString& aText, const VECTOR2I& aPosition,
-                                    const VECTOR2I& aSize, bool aItalic, const METRICS& aFontMetrics ) const;
+                                    const VECTOR2I& aSize, bool aItalic,
+                                    const METRICS& aFontMetrics ) const;
 
     void getLinePositions( const wxString& aText, const VECTOR2I& aPosition,
                            wxArrayString& aTextLines, std::vector<VECTOR2I>& aPositions,

include/font/fontconfig.h

@@ -65,8 +65,10 @@ public:
     /**
      * List the current available font families.
      *
-     * @param aDesiredLang The desired language of font name to report back if available, otherwise it will fallback
+     * @param aDesiredLang The desired language of font name to report back if available,
-     * @param aEmbeddedFiles A list of embedded to use for searching fonts, if nullptr, this is not used
+     *                     otherwise it will fallback.
+     * @param aEmbeddedFiles A list of embedded to use for searching fonts, if nullptr, this
+     *                       is not used
      * @param aForce If true, force rebuilding the font cache
      */
     void ListFonts( std::vector<std::string>& aFonts, const std::string& aDesiredLang,
@@ -85,12 +87,12 @@ private:
     static REPORTER*                s_reporter;
 
     /**
-     * Matches the two rfc 3306 language entries, used for when searching for matching family names
+     * Match two rfc 3306 language entries, used for when searching for matching family names
      *
-     * The overall logic is simple, either both language tags matched exactly or one tag is "single" level
+     * The overall logic is simple, either both language tags matched exactly or one tag is
-     * that the other language tag contains.
+     * "single" level that the other language tag contains.  There are nuances to language tags
-     * There's nuances to language tags beyond this but font tags will most likely never be more complex than
+     * beyond this but font tags will most likely never be more complex than say "zh-CN" or
-     * say "zh-CN" or single tag "en".
+     * single tag "en".
      *
      * @param aSearchLang the language being searched for
      * @param aSupportedLang the language being offered
@@ -98,17 +100,20 @@ private:
     bool isLanguageMatch( const wxString& aSearchLang, const wxString& aSupportedLang );
 
     /**
-     * Gets a list of all family name strings maped to lang
+     * Get a list of all family name strings mapped to lang
      *
      * @param aPat reference to FcPattern container
-     * @param aFamStringMap Map to be populated with key, value pairs representing lang to family name
+     * @param aFamStringMap Map to be populated with key, value pairs representing lang to
+     *                      family name
      */
     void getAllFamilyStrings( FONTCONFIG_PAT&                               aPat,
                               std::unordered_map<std::string, std::string>& aFamStringMap );
 
     /**
-     * Gets a family name based on desired language.
+     * Get a family name based on desired language.
-     * This will fallback to english or first available string if no language matching string is found.
+     *
+     * This will fallback to English or first available string if no language matching string
+     * is found.
      *
      * @param aPat reference to FcPattern container
      * @param aDesiredLang Language to research for (RFC3066 format)

include/font/glyph.h

@@ -89,7 +89,8 @@ public:
      * Cache the triangulation for the glyph from a known set of triangle indexes.
      * (See GetTriangulationData() above for more info.)
      */
-    void CacheTriangulation( std::vector<std::unique_ptr<SHAPE_POLY_SET::TRIANGULATED_POLYGON>>& aHintData );
+    void CacheTriangulation(
+            std::vector<std::unique_ptr<SHAPE_POLY_SET::TRIANGULATED_POLYGON>>& aHintData );
 };
 
 

include/font/outline_decomposer.h

@@ -43,6 +43,7 @@ namespace KIFONT
 {
 
 constexpr int GLYPH_DEFAULT_DPI = 72;  ///< FreeType default
+
 // The FreeType default of 72 DPI is not enough for outline decomposition;
 // so we'll use something larger than that.
 constexpr int GLYPH_RESOLUTION  = 1152;

include/font/outline_font.h

@@ -92,6 +92,7 @@ public:
 
     /**
      * Load an outline font. TrueType (.ttf) and OpenType (.otf) are supported.
+     *
      * @param aFontFileName is the (platform-specific) fully qualified name of the font file
      */
     static OUTLINE_FONT* LoadFont( const wxString& aFontFileName, bool aBold, bool aItalic,
@@ -99,8 +100,9 @@ public:
                                    bool aForDrawingSheet );
 
     /**
-     * Compute the distance (interline) between 2 lines of text (for multiline texts).  This is
+     * Compute the distance (interline) between 2 lines of text (for multiline texts).
-     * the distance between baselines, not the space between line bounding boxes.
+     *
+     * This is the distance between baselines, not the space between line bounding boxes.
      */
     double GetInterline( double aGlyphHeight, const METRICS& aFontMetrics ) const override;
 
@@ -182,6 +184,7 @@ private:
     {
         return aSize * m_charSizeScaler * m_outlineFontSizeCompensation;
     };
+
     int faceSize() const { return faceSize( m_faceSize ); }
 
     // also for superscripts

include/font/stroke_font.h

@@ -66,8 +66,9 @@ public:
     static STROKE_FONT* LoadFont( const wxString& aFontName );
 
     /**
-     * Compute the distance (interline) between 2 lines of text (for multiline texts).  This is
+     * Compute the distance (interline) between 2 lines of text (for multiline texts).
-     * the distance between baselines, not the space between line bounding boxes.
+     *
+     * This is the distance between baselines, not the space between line bounding boxes.
      */
     double GetInterline( double aGlyphHeight, const METRICS& aFontMetrics ) const override;
 

include/font/text_attributes.h

@@ -38,7 +38,7 @@ class FONT;
 // NB: values -1,0,1 are used in computations, do not change them
 //
 
-// This is API surface mapped to common.types.HorizontalAlignment
+/// This is API surface mapped to common.types.HorizontalAlignment
 enum GR_TEXT_H_ALIGN_T
 {
     GR_TEXT_H_ALIGN_LEFT   = -1,
@@ -47,7 +47,7 @@ enum GR_TEXT_H_ALIGN_T
     GR_TEXT_H_ALIGN_INDETERMINATE
 };
 
-// This is API surface mapped to common.types.VertialAlignment
+/// This is API surface mapped to common.types.VertialAlignment
 enum GR_TEXT_V_ALIGN_T
 {
     GR_TEXT_V_ALIGN_TOP    = -1,
@@ -58,8 +58,7 @@ enum GR_TEXT_V_ALIGN_T
 
 
 /**
- * Get the reverse alignment: left-right are swapped,
+ * Get the reverse alignment: left-right are swapped, others are unchanged.
- * others are unchanged.
  */
 constexpr GR_TEXT_H_ALIGN_T GetFlippedAlignment( GR_TEXT_H_ALIGN_T aAlign )
 {
@@ -79,8 +78,7 @@ constexpr GR_TEXT_H_ALIGN_T GetFlippedAlignment( GR_TEXT_H_ALIGN_T aAlign )
 
 
 /**
- * Get the reverse alignment: top-bottom are swapped,
+ * Get the reverse alignment: top-bottom are swapped, others are unchanged.
- * others are unchanged.
  */
 constexpr GR_TEXT_V_ALIGN_T GetFlippedAlignment( GR_TEXT_V_ALIGN_T aAlign )
 {
@@ -149,7 +147,8 @@ public:
 };
 
 
-extern GAL_API std::ostream& operator<<( std::ostream& aStream, const TEXT_ATTRIBUTES& aAttributes );
+extern GAL_API std::ostream& operator<<( std::ostream& aStream,
+                                         const TEXT_ATTRIBUTES& aAttributes );
 
 
 template<>

include/gal/gal_display_options.h

@@ -41,7 +41,7 @@ class wxWindow;
 namespace KIGFX
 {
     /**
-     * GRID_STYLE: Type definition of the grid style
+     * Type definition of the grid style.
      */
     enum class GRID_STYLE
     {
@@ -77,6 +77,7 @@ namespace KIGFX
     {
     public:
         virtual void OnGalDisplayOptionsChanged( const GAL_DISPLAY_OPTIONS& ) = 0;
+
     protected:
         // Observer lifetimes aren't handled by base class pointer
         virtual ~GAL_DISPLAY_OPTIONS_OBSERVER() {}

include/gal/gal_print.h

@@ -39,7 +39,7 @@ public:
 
 
 /**
- * @brief Wrapper around GAL to provide information needed for printing.
+ * Wrapper around GAL to provide information needed for printing.
  */
 class GAL_API GAL_PRINT
 {

include/gal/graphics_abstraction_layer.h

@@ -161,6 +161,9 @@ public:
      * DrawArcSegment() with fill *on* behaves like DrawArc() with fill *off*.
      * DrawArcSegment() with fill *off* draws the outline of what it would have drawn with fill on.
      *
+     * This has meaning only for back ends that can't draw a true arc, and use segments to
+     * approximate.
+     *
      * TODO: Unify Arc routines
      *
      * @param aCenterPoint  is the center point of the arc.
@@ -169,7 +172,6 @@ public:
      * @param aAngle        is the angle of the arc.
      * @param aWidth        is the thickness of the arc (pen size).
      * @param aMaxError     is the max allowed error to create segments to approximate a circle.
-     *  It has meaning only for back ends that can't draw a true arc, and use segments to approximate.
      */
     virtual void DrawArcSegment( const VECTOR2D& aCenterPoint, double aRadius,
                                  const EDA_ANGLE& aStartAngle, const EDA_ANGLE& aAngle,
@@ -210,7 +212,8 @@ public:
      */
     virtual void DrawPolygon( const std::deque<VECTOR2D>& aPointList ) {};
     virtual void DrawPolygon( const VECTOR2D aPointList[], int aListSize ) {};
-    virtual void DrawPolygon( const SHAPE_POLY_SET& aPolySet, bool aStrokeTriangulation = false ) {};
+    virtual void DrawPolygon( const SHAPE_POLY_SET& aPolySet,
+                              bool aStrokeTriangulation = false ) {};
     virtual void DrawPolygon( const SHAPE_LINE_CHAIN& aPolySet ) {};
 
     /**
@@ -386,8 +389,10 @@ public:
      */
     virtual void SetLayerDepth( double aLayerDepth )
     {
-        wxCHECK_MSG( aLayerDepth <= m_depthRange.y, /*void*/, wxT( "SetLayerDepth: below minimum" ) );
+        wxCHECK_MSG( aLayerDepth <= m_depthRange.y, /*void*/,
-        wxCHECK_MSG( aLayerDepth >= m_depthRange.x, /*void*/, wxT( "SetLayerDepth: above maximum" ) );
+                     wxT( "SetLayerDepth: below minimum" ) );
+        wxCHECK_MSG( aLayerDepth >= m_depthRange.x, /*void*/,
+                     wxT( "SetLayerDepth: above maximum" ) );
 
         m_layerDepth = aLayerDepth;
     }
@@ -1007,7 +1012,7 @@ protected:
     }
 
     /**
-     * compute minimum grid spacing from the grid settings
+     * Compute minimum grid spacing from the grid settings.
      *
      * @return the minimum spacing to use for drawing the grid
      */
@@ -1021,7 +1026,7 @@ protected:
     static const int GRID_DEPTH;
 
     /**
-     * Get the actual cursor color to draw
+     * Get the actual cursor color to draw.
      */
     COLOR4D getCursorColor() const;
 
@@ -1044,7 +1049,7 @@ protected:
     virtual bool updatedGalDisplayOptions( const GAL_DISPLAY_OPTIONS& aOptions );
 
     /**
-     * Ensure that the first element is smaller than the second
+     * Ensure that the first element is smaller than the second.
      */
     template <typename T>
     void normalize( T &a, T &b )
@@ -1207,7 +1212,7 @@ public:
     };
 
     /**
-     * Instantiates a GAL_SCOPED_ATTRS object, saving the current attributes of the GAL.
+     * Instantiate a GAL_SCOPED_ATTRS object, saving the current attributes of the GAL.
      *
      * Specify the flags to save/restore in aFlags.
      */
@@ -1231,13 +1236,16 @@ public:
 
         if( m_flags & STROKE_WIDTH )
             m_gal.SetLineWidth( m_strokeWidth );
+
         if( m_flags & STROKE_COLOR )
             m_gal.SetStrokeColor( m_strokeColor );
+
         if( m_flags & IS_STROKE )
             m_gal.SetIsStroke( m_isStroke );
 
         if( m_flags & FILL_COLOR )
             m_gal.SetFillColor( m_fillColor );
+
         if( m_flags & IS_FILL )
             m_gal.SetIsFill( m_isFill );
 

include/gal/opengl/gl_utils.h

@@ -41,7 +41,7 @@ class GL_UTILS
 {
 public:
     /**
-     * Attempts to set the OpenGL swap interval.
+     * Attempt to set the OpenGL swap interval.
      *
      * @param aVal if -1 = try to set adaptive swapping, 0 = sync off, 1 = sync with VSYNC rate.
      * @return actual value set
@@ -112,7 +112,6 @@ public:
 #elif defined( _WIN32 )
 
         const GLubyte* vendor = glGetString( GL_VENDOR );
-        //const GLubyte* renderer = glGetString( GL_RENDERER );
         const GLubyte* version = glGetString( GL_VERSION );
 
         if( wglSwapIntervalEXT && wxGLCanvas::IsExtensionSupported( "WGL_EXT_swap_control" ) )

include/gal/opengl/gpu_manager.h

@@ -106,10 +106,12 @@ public:
     struct VRANGE
     {
         VRANGE( int aStart, int aEnd, bool aContinuous ) :
-        m_start( aStart ),
+                m_start( aStart ),
-        m_end( aEnd ),
+                m_end( aEnd ),
-        m_isContinuous ( aContinuous )
+                m_isContinuous( aContinuous )
-        {}
+        {
+        }
+
         unsigned int m_start, m_end;
         bool m_isContinuous;
     };
@@ -180,5 +182,7 @@ public:
     ///< @copydoc GPU_MANAGER::EndDrawing()
     virtual void EndDrawing() override;
 };
+
 } // namespace KIGFX
+
 #endif /* GPU_MANAGER_H_ */

include/gal/opengl/opengl_gal.h

@@ -282,10 +282,10 @@ public:
     void DrawCursor( const VECTOR2D& aCursorPosition ) override;
 
     /**
-     * @brief Function PostPaint
+     * Post an event to #m_paint_listener.
-     * posts an event to m_paint_listener.  A post is used so that the actual drawing
+     *
-     * function can use a device context type that is not specific to the wxEVT_PAINT event,
+     * A post is used so that the actual drawing function can use a device context type that
-     * just by changing the PostPaint code.
+     * is not specific to the wxEVT_PAINT event, just by changing the PostPaint code.
      */
     void PostPaint( wxPaintEvent& aEvent );
 
@@ -349,7 +349,9 @@ private:
     VERTEX_MANAGER*         m_cachedManager;    ///< Container for storing cached VERTEX_ITEMs
     VERTEX_MANAGER*         m_nonCachedManager; ///< Container for storing non-cached VERTEX_ITEMs
     VERTEX_MANAGER*         m_overlayManager;   ///< Container for storing overlaid VERTEX_ITEMs
-    VERTEX_MANAGER*         m_tempManager;      ///< Container for storing temp (diff mode) VERTEX_ITEMs
+
+    /// Container for storing temp (diff mode) VERTEX_ITEMs
+    VERTEX_MANAGER*         m_tempManager;
 
     // Framebuffer & compositing
     OPENGL_COMPOSITOR*      m_compositor;       ///< Handles multiple rendering targets
@@ -359,8 +361,8 @@ private:
     RENDER_TARGET           m_currentTarget;    ///< Current rendering target
 
     // Shader
-    SHADER*                 m_shader;           ///< There is only one shader used for different
+    /// There is only one shader used for different objects.
-                                                ///< objects.
+    SHADER*                 m_shader;
 
     // Internal flags
     bool                    m_isFramebufferInitialized; ///< Are the framebuffers initialized?
@@ -376,7 +378,8 @@ private:
     GLint                   ufm_pixelSizeMultiplier;
     GLint                   ufm_antialiasingOffset;
 
-    wxCursor                m_currentwxCursor;          ///< wxCursor showing the current native cursor
+    /// wxCursor showing the current native cursor.
+    wxCursor                m_currentwxCursor;
 
     std::unique_ptr<GL_BITMAP_CACHE>            m_bitmapCache;
 
@@ -394,7 +397,7 @@ private:
     bool updatedGalDisplayOptions( const GAL_DISPLAY_OPTIONS& aOptions ) override;
 
     /**
-     * @brief Draw a quad for the line.
+     * Draw a quad for the line.
      *
      * @param aStartPoint is the start point of the line.
      * @param aEndPoint is the end point of the line.
@@ -405,7 +408,7 @@ private:
                        bool aReserve = true );
 
     /**
-     * @brief Reserves specified number of line quads.
+     * Reserve specified number of line quads.
      *
      * @param aLineCount the number of line quads to reserve.
      */

include/gal/opengl/shader.h

@@ -82,13 +82,13 @@ public:
     virtual ~SHADER();
 
     /**
-    * Add a shader and compile the shader sources.
+     * Add a shader and compile the shader sources.
-    *
+     *
-    * @param aArgs is the list of strings (std::string or convertible to const char*) which
+     * @param aArgs is the list of strings (std::string or convertible to const char*) which
-    *              are concatenated and compiled as a single shader source code.
+     *              are concatenated and compiled as a single shader source code.
-    * @param aShaderType is the type of the shader.
+     * @param aShaderType is the type of the shader.
-    * @return True in case of success, false otherwise.
+     * @return True in case of success, false otherwise.
-    */
+     */
     template< typename... Args >
     bool LoadShaderFromStrings( SHADER_TYPE aShaderType, Args&&... aArgs )
     {
@@ -190,11 +190,11 @@ public:
     int GetAttribute( const std::string& aAttributeName ) const;
 
     /**
-    * Read the shader source file
+     * Read the shader source file
-    *
+     *
-    * @param aShaderSourceName is the shader source file name.
+     * @param aShaderSourceName is the shader source file name.
-    * @return the source as string
+     * @return the source as string
-    */
+     */
     static std::string ReadSource( const std::string& aShaderSourceName );
 
 private:

include/gal/opengl/vertex_common.h

@@ -64,23 +64,25 @@ struct VERTEX
     GLfloat shader[4];      // Shader type & params
 };
 
-static constexpr size_t VERTEX_SIZE   = sizeof(VERTEX);
+static constexpr size_t VERTEX_SIZE   = sizeof( VERTEX );
-static constexpr size_t VERTEX_STRIDE = VERTEX_SIZE / sizeof(GLfloat);
+static constexpr size_t VERTEX_STRIDE = VERTEX_SIZE / sizeof( GLfloat );
 
-static constexpr size_t COORD_OFFSET  = offsetof(VERTEX, x);
+static constexpr size_t COORD_OFFSET  = offsetof( VERTEX, x );
-static constexpr size_t COORD_SIZE    = sizeof(VERTEX::x) + sizeof(VERTEX::y) + sizeof(VERTEX::z);
+static constexpr size_t COORD_SIZE    = sizeof( VERTEX::x ) + sizeof( VERTEX::y ) +
-static constexpr size_t COORD_STRIDE  = COORD_SIZE / sizeof(GLfloat);
+                                        sizeof( VERTEX::z );
+static constexpr size_t COORD_STRIDE  = COORD_SIZE / sizeof( GLfloat );
 
-static constexpr size_t COLOR_OFFSET  = offsetof(VERTEX, r);
+static constexpr size_t COLOR_OFFSET = offsetof( VERTEX, r );
-static constexpr size_t COLOR_SIZE    = sizeof(VERTEX::r) + sizeof(VERTEX::g) + sizeof(VERTEX::b) + sizeof(VERTEX::a);
+static constexpr size_t COLOR_SIZE = sizeof( VERTEX::r ) + sizeof( VERTEX::g ) +
-static constexpr size_t COLOR_STRIDE  = COLOR_SIZE / sizeof(GLubyte);
+                                     sizeof( VERTEX::b ) + sizeof( VERTEX::a );
+static constexpr size_t COLOR_STRIDE = COLOR_SIZE / sizeof( GLubyte );
 
 // Shader attributes
-static constexpr size_t SHADER_OFFSET = offsetof(VERTEX, shader);
+static constexpr size_t SHADER_OFFSET = offsetof( VERTEX, shader );
-static constexpr size_t SHADER_SIZE   = sizeof(VERTEX::shader);
+static constexpr size_t SHADER_SIZE = sizeof( VERTEX::shader );
-static constexpr size_t SHADER_STRIDE = SHADER_SIZE / sizeof(GLfloat);
+static constexpr size_t SHADER_STRIDE = SHADER_SIZE / sizeof( GLfloat );
 
-static constexpr size_t INDEX_SIZE    = sizeof(GLuint);
+static constexpr size_t INDEX_SIZE = sizeof( GLuint );
 
 } // namespace KIGFX
 

include/gal/opengl/vertex_manager.h

@@ -133,7 +133,7 @@ public:
     bool Vertices( const VERTEX aVertices[], unsigned int aSize );
 
     /**
-     * Changes currently used color that will be applied to newly added vertices.
+     * Change currently used color that will be applied to newly added vertices.
      *
      * @param aColor is the new color.
      */
@@ -361,18 +361,23 @@ protected:
 
     /// Container for vertices, may be cached or noncached
     std::shared_ptr<VERTEX_CONTAINER> m_container;
+
     /// GPU manager for data transfers and drawing operations
     std::shared_ptr<GPU_MANAGER>      m_gpu;
 
     /// State machine variables
     /// True in case there is no need to transform vertices
     bool                    m_noTransform;
+
     /// Currently used transform matrix
     glm::mat4               m_transform;
+
     /// Stack of transformation matrices, used for Push/PopMatrix
     std::stack<glm::mat4>   m_transformStack;
+
     /// Currently used color
     GLubyte                 m_color[COLOR_STRIDE];
+
     /// Currently used shader and its parameters
     GLfloat                 m_shader[SHADER_STRIDE];
 

include/http_lib/http_lib_connection.h

@@ -69,8 +69,9 @@ public:
     auto& getCachedParts() { return m_cache; }
 
 private:
-    // This is clunky but at the moment the only way to free the pointer after use without KiCad crashing.
+    // This is clunky but at the moment the only way to free the pointer after use without
-    // at this point we can't use smart pointers as there is a problem with the order of how things are deleted/freed
+    // KiCad crashing.  At this point we can't use smart pointers as there is a problem with
+    // the order of how things are deleted/freed
     std::unique_ptr<KICAD_CURL_EASY> createCurlEasyObject()
     {
         std::unique_ptr<KICAD_CURL_EASY> aCurl( new KICAD_CURL_EASY() );

include/io/io_base.h

@@ -42,8 +42,12 @@ public:
     struct KICOMMON_API IO_FILE_DESC
     {
         wxString                 m_Description;    ///< Description shown in the file picker dialog
-        std::vector<std::string> m_FileExtensions; ///< Filter used for file pickers if m_IsFile is true
+
-        std::vector<std::string> m_ExtensionsInDir; ///< In case of folders: extensions of files inside
+        /// Filter used for file pickers if m_IsFile is true.
+        std::vector<std::string> m_FileExtensions;
+
+        ///< In case of folders: extensions of files inside.
+        std::vector<std::string> m_ExtensionsInDir;
         bool                     m_IsFile;          ///< Whether the library is a folder or a file
         bool                     m_CanRead;         ///< Whether the IO can read this file type
         bool                     m_CanWrite;        ///< Whether the IO can write this file type
@@ -82,8 +86,10 @@ public:
     /**
      * Set an optional progress reporter.
      */
-    virtual void SetProgressReporter( PROGRESS_REPORTER* aReporter ) { m_progressReporter = aReporter; }
+    virtual void SetProgressReporter( PROGRESS_REPORTER* aReporter )
-
+    {
+        m_progressReporter = aReporter;
+    }
 
     ////////////////////////////////////////////////////
     // Library-related functions
@@ -98,8 +104,8 @@ public:
 
     /**
      * Get the descriptor for the individual library elements that this IO plugin operates on.
-     * For libraries where all the elements are in a single container (e.g. all elements in a single file),
+     * For libraries where all the elements are in a single container (e.g. all elements in a
-     * then this will return the descriptor from #IO_BASE::GetLibraryDesc().
+     * single file), then this will return the descriptor from #IO_BASE::GetLibraryDesc().
      *
      * @return File descriptor for the library elements
      */
@@ -107,7 +113,7 @@ public:
 
     /**
      * Checks if this IO object can read the specified library file/directory.
-     * If not overriden, extension check is used.
+     * If not overridden, extension check is used.
      *
      * @note This is not a check that the file system object is readable by the user,
      *       but a check that this IO object can parse the given library.
@@ -186,8 +192,8 @@ public:
      *  In the future perhaps \a aListToAppendTo evolves to something capable of also
      *  holding a wxValidator for the cells in said dialog:
      *  http://forums.wxwidgets.org/viewtopic.php?t=23277&p=104180.
-     *   This would require a 3 column list, and introducing wx GUI knowledge to
+     *  This would require a 3 column list, and introducing wx GUI knowledge to
-     *   #SCH_IO, which has been avoided to date.
+     *  #SCH_IO, which has been avoided to date.
      */
     virtual void GetLibraryOptions( std::map<std::string, UTF8>* aListToAppendTo ) const;
 
@@ -200,7 +206,6 @@ protected:
     IO_BASE() = delete;
 
     /**
-     *
      * @param aName is the user-visible name for the IO loader
      */
     IO_BASE( const wxString& aName ) :

include/kicad_curl/kicad_curl_easy.h

@@ -101,7 +101,8 @@ public:
     bool SetPostFields( const std::vector<std::pair<std::string, std::string>>& aFields );
 
     /**
-     * Set the post content body to the string, usually used for json rather than the typical key/value pair
+     * Set the post content body to the string, usually used for json rather than the typical
+     * key/value pair.
      *
      * @param aField is the string body to send
      * @return True if successful, false if not.

include/plotters/plotter.h

@@ -113,7 +113,7 @@ public:
     virtual ~PLOTTER();
 
     /**
-     * Returns the effective plot engine in use. It's not very OO but for
+     * Return the effective plot engine in use. It's not very OO but for
      * now is required since some things are only done with some output devices
      * (like drill marks, emitted only for postscript
      */
@@ -222,9 +222,9 @@ public:
                       int aWidth = USE_DEFAULT_LINE_WIDTH );
 
     /**
-     * Generic fallback: Cubic Bezier curve rendered as a polyline
+     * Generic fallback: Cubic Bezier curve rendered as a polyline.
-     * In KiCad the bezier curves have 4 control points:
+     *
-     * start ctrl1 ctrl2 end
+     * In KiCad the bezier curves have 4 control points: start ctrl1 ctrl2 end
      */
     virtual void BezierCurve( const VECTOR2I& aStart, const VECTOR2I& aControl1,
                               const VECTOR2I& aControl2, const VECTOR2I& aEnd,
@@ -276,6 +276,7 @@ public:
 
     /**
      * Draw a polygon ( filled or not ).
+     *
      * @param aCornerList is the corners list (a SHAPE_LINE_CHAIN).
      *        must be closed (IsClosed() == true) for a polygon. Otherwise this is a polyline.
      * @param aFill is the type of fill.
@@ -308,8 +309,8 @@ public:
                            const EDA_ANGLE& aAngle, double aRadius, int aWidth,
                            OUTLINE_MODE aTraceMode, void* aData );
 
-    virtual void ThickRect( const VECTOR2I& p1, const VECTOR2I& p2, int width, OUTLINE_MODE tracemode,
+    virtual void ThickRect( const VECTOR2I& p1, const VECTOR2I& p2, int width,
-                            void* aData );
+                            OUTLINE_MODE tracemode, void* aData );
 
     virtual void ThickCircle( const VECTOR2I& pos, int diametre, int width, OUTLINE_MODE tracemode,
                               void* aData );
@@ -418,7 +419,8 @@ public:
      * @param aV_justify is the vertical justification (bottom, center, top).
      * @param aPenWidth is the line width (if = 0, use plot default line width).
      * @param aItalic is the true to simulate an italic font.
-     * @param aBold use true to use a bold font Useful only with default width value (aPenWidth = 0).
+     * @param aBold use true to use a bold font Useful only with default width value
+     *              (aPenWidth = 0).
      * @param aMultilineAllowed use true to plot text as multiline, otherwise single line.
      * @param aData is a parameter used by some plotters in SetCurrentLineWidth(),
      *              not directly used here.
@@ -508,8 +510,9 @@ public:
     }
 
     /**
-     * Change the current text mode. See the PlotTextMode
+     * Change the current text mode.
-     * explanation at the beginning of the file.
+     *
+     * See the PlotTextMode explanation at the beginning of the file.
      */
     virtual void SetTextMode( PLOT_TEXT_MODE mode )
     {
@@ -546,8 +549,7 @@ public:
     virtual void EndBlock( void* aData ) {}
 
     /**
-     * @return the plot offset in IUs, set by SetViewport() and used
+     * @return the plot offset in IUs, set by SetViewport() and used to plot items.
-     * to plot items.
      */
     VECTOR2I GetPlotOffsetUserUnits() {return m_plotOffset; }
 
@@ -641,6 +643,7 @@ protected:
 
 
 protected:      // variables used in most of plotters:
+
     /// Plot scale - chosen by the user (even implicitly with 'fit in a4')
     double           m_plotScale;
 
@@ -692,8 +695,9 @@ void PlotDrawingSheet( PLOTTER* plotter, const PROJECT* aProject, const TITLE_BL
                        const wxString& aSheetPath, const wxString& aFilename,
                        COLOR4D aColor = COLOR4D::UNSPECIFIED, bool aIsFirstPage = true );
 
-/** Returns the default plot extension for a format
+/**
-  */
+ * Return the default plot extension for a format.
+ */
 wxString GetDefaultPlotExtension( PLOT_FORMAT aFormat );
 
 

include/plotters/plotters_pslike.h

@@ -288,7 +288,8 @@ public:
     /**
      * Start a new page in the PDF document.
      */
-    virtual void StartPage( const wxString& aPageNumber, const wxString& aPageName = wxEmptyString );
+    virtual void StartPage( const wxString& aPageNumber,
+                            const wxString& aPageName = wxEmptyString );
 
     /**
      * Close the current page in the PDF document (and emit its compressed stream).
@@ -371,7 +372,8 @@ public:
 
     void HyperlinkMenu( const BOX2I& aBox, const std::vector<wxString>& aDestURLs ) override;
 
-    void Bookmark( const BOX2I& aBox, const wxString& aName, const wxString& aGroupName = wxEmptyString ) override;
+    void Bookmark( const BOX2I& aBox, const wxString& aName,
+                   const wxString& aGroupName = wxEmptyString ) override;
 
     /**
      * PDF images are handles as inline, not XObject streams...
@@ -411,12 +413,13 @@ protected:
     };
 
     /**
-     * Adds a new outline node entry
+     * Add a new outline node entry.
      *
-     * The PDF object handle is automacially allocated
+     * The PDF object handle is automatically allocated.
      *
-     * @param aParent Parent node to append the new node to
+     * @param aParent Parent node to append the new node to.
-     * @param aActionHandle The handle of an action that may be performed on click, set to -1 for no action
+     * @param aActionHandle The handle of an action that may be performed on click, set to -1
+     *                      for no action.
      * @param aTitle Title of node to display
      */
     OUTLINE_NODE* addOutlineNode( OUTLINE_NODE* aParent, int aActionHandle,
@@ -438,8 +441,9 @@ protected:
     virtual void emitSetRGBColor( double r, double g, double b, double a ) override;
 
     /**
-     * Allocate a new handle in the table of the PDF object. The
+     * Allocate a new handle in the table of the PDF object.
-     * handle must be completed using startPdfObject. It's an in-RAM operation
+     *
+     * The handle must be completed using startPdfObject. It's an in-RAM operation
      * only, no output is done.
      */
     int allocPdfObject();
@@ -448,7 +452,7 @@ protected:
      * Open a new PDF object and returns the handle if the parameter is -1.
      * Otherwise fill in the xref entry for the passed object
      */
-    int startPdfObject(int handle = -1);
+    int startPdfObject( int handle = -1 );
 
     /**
      * Close the current PDF object
@@ -456,56 +460,57 @@ protected:
     void closePdfObject();
 
     /**
-     * Starts a PDF stream (for the page). Returns the object handle opened
+     * Start a PDF stream (for the page).
-     * Pass -1 (default) for a fresh object. Especially from PDF 1.5 streams
+     *
-     * can contain a lot of things, but for the moment we only handle page
+     * @param handle -1 (default) for a new object. Especially from PDF 1.5 streams can contain
-     * content.
+     *               a lot of things, but for the moment we only handle page content.
+     * @eturn The object handle opened
      */
-    int startPdfStream(int handle = -1);
+    int startPdfStream( int handle = -1 );
 
     /**
-     * Finish the current PDF stream (writes the deferred length, too)
+     * Finish the current PDF stream (writes the deferred length, too).
      */
     void closePdfStream();
 
     /**
-     * Starts emitting the outline object
+     * Starts emitting the outline object.
      */
     int emitOutline();
 
     /**
-     * Emits a outline item object and recurses into any children
+     * Emits a outline item object and recurses into any children.
      */
     void emitOutlineNode( OUTLINE_NODE* aNode, int aParentHandle, int aNextNode, int aPrevNode );
 
     /**
-     * Emits an action object that instructs a goto coordinates on a page
+     * Emit an action object that instructs a goto coordinates on a page.
      *
-     * @return Generated action handle
+     * @return Generated action handle.
      */
     int emitGoToAction( int aPageHandle, const VECTOR2I& aBottomLeft, const VECTOR2I& aTopRight );
     int emitGoToAction( int aPageHandle );
 
-    int m_pageTreeHandle;           ///< Handle to the root of the page tree object
+    int m_pageTreeHandle;           ///< Handle to the root of the page tree object.
-    int m_fontResDictHandle;        ///< Font resource dictionary
+    int m_fontResDictHandle;        ///< Font resource dictionary.
-    int m_imgResDictHandle;         ///< Image resource dictionary
+    int m_imgResDictHandle;         ///< Image resource dictionary.
-    int m_jsNamesHandle;            ///< Handle for Names dictionary with JS
+    int m_jsNamesHandle;            ///< Handle for Names dictionary with JS.
-    std::vector<int> m_pageHandles; ///< Handles to the page objects
+    std::vector<int> m_pageHandles; ///< Handles to the page objects.
-    int m_pageStreamHandle;         ///< Handle of the page content object
+    int m_pageStreamHandle;         ///< Handle of the page content object.
-    int m_streamLengthHandle;       ///< Handle to the deferred stream length
+    int m_streamLengthHandle;       ///< Handle to the deferred stream length.
     wxString m_workFilename;
     wxString m_pageName;
-    FILE* m_workFile;               ///< Temporary file to construct the stream before zipping
+    FILE* m_workFile;               ///< Temporary file to construct the stream before zipping.
-    std::vector<long> m_xrefTable;  ///< The PDF xref offset table
+    std::vector<long> m_xrefTable;  ///< The PDF xref offset table.
 
-    ///< List of user-space page numbers for resolving internal hyperlinks
+    /// List of user-space page numbers for resolving internal hyperlinks.
     std::vector<wxString>                                  m_pageNumbers;
 
-    ///< List of loaded hyperlinks in current page
+    /// List of loaded hyperlinks in current page.
     std::vector<std::pair<BOX2I, wxString>>                m_hyperlinksInPage;
     std::vector<std::pair<BOX2I, std::vector<wxString>>>   m_hyperlinkMenusInPage;
 
-    ///< Handles for all the hyperlink objects that will be deferred
+    /// Handles for all the hyperlink objects that will be deferred.
     std::map<int, std::pair<BOX2D, wxString>>              m_hyperlinkHandles;
     std::map<int, std::pair<BOX2D, std::vector<wxString>>> m_hyperlinkMenuHandles;
 
@@ -513,8 +518,8 @@ protected:
 
     std::map<int, wxImage> m_imageHandles;
 
-    std::unique_ptr<OUTLINE_NODE> m_outlineRoot;    ///< Root outline node
+    std::unique_ptr<OUTLINE_NODE> m_outlineRoot;        ///< Root outline node.
-    int                           m_totalOutlineNodes;  ///< Total number of outline nodes
+    int                           m_totalOutlineNodes;  ///< Total number of outline nodes.
 };
 
 

include/plugins/3d/3d_plugin.h

@@ -24,19 +24,15 @@
 
 /**
  * @file 3d_plugin.h
- * describes the runtime-loadable interface to support loading
+ *
- * and parsing of 3D models.
+ * Describe the runtime-loadable interface to support loading and parsing of 3D models.
+ *
+ * @warning Do not edit this file outside the KiCad tree.
  */
 
 #ifndef PLUGIN_3D_H
 #define PLUGIN_3D_H
 
-//
-// KICAD_PLUGIN CLASS INTERFACE
-//
-// WARNING: DO NOT EDIT THIS FILE OUTSIDE THE KICAD TREE
-//
-
 // Note: the plugin class name must match the name expected by the loader
 #define KICAD_PLUGIN_CLASS "PLUGIN_3D"
 #define MAJOR 1
@@ -53,8 +49,8 @@ KICAD_PLUGIN_EXPORT char const* GetKicadPluginClass( void )
 }
 
 
-KICAD_PLUGIN_EXPORT void GetClassVersion( unsigned char* Major,
+KICAD_PLUGIN_EXPORT void GetClassVersion( unsigned char* Major, unsigned char* Minor,
-    unsigned char* Minor, unsigned char* Patch, unsigned char* Revision )
+                                          unsigned char* Patch, unsigned char* Revision )
 {
     if( Major )
         *Major = MAJOR;
@@ -71,8 +67,8 @@ KICAD_PLUGIN_EXPORT void GetClassVersion( unsigned char* Major,
     return;
 }
 
-KICAD_PLUGIN_EXPORT bool CheckClassVersion( unsigned char Major,
+KICAD_PLUGIN_EXPORT bool CheckClassVersion( unsigned char Major, unsigned char Minor,
-    unsigned char Minor, unsigned char Patch, unsigned char Revision )
+                                            unsigned char Patch, unsigned char Revision )
 {
     if( Major != MAJOR )
         return false;
@@ -85,50 +81,38 @@ KICAD_PLUGIN_EXPORT bool CheckClassVersion( unsigned char Major,
 class SCENEGRAPH;
 
 /**
- * Function GetNExtensions
+ * @return the number of extensions supported by the plugin.
- *
- * @return the number of extensions supported by the plugin
  */
 KICAD_PLUGIN_EXPORT int GetNExtensions( void );
 
 /**
- * Function GetModelExtension
+ * @param aIndex is the extension to return; valid values are 0 to GetNExtensions() - 1.
- *
+ * @return the requested extension or a null string if aIndex was invalid.
- * @param aIndex is the extension to return; valid values are
- * 0 to GetNExtensions() - 1.
- * @return the requested extension or a null string if aIndex
- * was invalid.
  */
 KICAD_PLUGIN_EXPORT char const* GetModelExtension( int aIndex );
 
 /**
- * Function GetNFilters
+ * @returns the number of file filters.
- * @returns the number of file filters
  */
 KICAD_PLUGIN_EXPORT int GetNFilters( void );
 
 /**
- * Function GetFileFilter
+ * @return the file filter string for the given index.
- *
- * @return the file filter string for the given index
  */
 KICAD_PLUGIN_EXPORT char const* GetFileFilter( int aIndex );
 
 /**
- * Function CanRender
+ * @return true if the plugin can render a model, that is the Load() function is implemented.
- *
- * @return true if the plugin can render a model, that is
- * the Load() function is implemented
  */
 KICAD_PLUGIN_EXPORT bool CanRender( void );
 
 /**
- * reads a model file and creates a generic display structure
+ * Read a model file and creates a generic display structure.
  *
- * @param aFileName is the full path of the model file
+ * @param aFileName is the full path of the model file.
- * @return a SCENEGRAPH pointer to the display structure if the model
+ * @return a #SCENEGRAPH pointer to the display structure if the model was successfully loaded
- * was successfully loaded and NULL if there is no rendering support
+ *         and NULL if there is no rendering support for the model or there were problems reading
- * for the model or there were problems reading the model
+ *         the model.
  */
 KICAD_PLUGIN_EXPORT SCENEGRAPH* Load( char const* aFileName );
 

include/plugins/3dapi/c3dmodel.h

@@ -57,22 +57,26 @@ struct SMATERIAL
 };
 
 
-/// Per-vertex normal/color/texcoors structure.
+/**
-/// CONDITIONS:
+ * Per-vertex normal/color/texcoors structure.
-///     m_Positions size == m_Normals size == m_Texcoords size == m_Color size
+ *
-///     m_Texcoords can be NULL, textures will not be applied in that case
+ * CONDITIONS:
-///     m_Color can be NULL, it will use the m_Diffuse color for every triangle
+ *     m_Positions size == m_Normals size == m_Texcoords size == m_Color size
-///     any m_FaceIdx must be an index of a the element lists
+ *     m_Texcoords can be NULL, textures will not be applied in that case
-///     m_MaterialIdx must be an existent material index stored in the parent model
+ *     m_Color can be NULL, it will use the m_Diffuse color for every triangle
-/// SCALES:
+ *     any m_FaceIdx must be an index of a the element lists
-/// m_Positions units are in mm, example:
+ *     m_MaterialIdx must be an existent material index stored in the parent model
-///  0.1 unit ==  0.1 mm
+ *
-///  1.0 unit ==  1.0 mm
+ * SCALES:
-/// 10.0 unit == 10.0 mm
+ *     m_Positions units are in mm, example:
-///
+ *          0.1 unit ==  0.1 mm
-/// To convert this units to pcbunits, use the conversion facto UNITS3D_TO_UNITSPCB
+ *          1.0 unit ==  1.0 mm
-///
+ *          10.0 unit == 10.0 mm
-/// m_Normals, m_Color and m_Texcoords are between 0.0f and 1.0f
+ *
+ * To convert this units to pcbunits, use the conversion factor #UNITS3D_TO_UNITSPCB.
+ *
+ * m_Normals, m_Color and m_Texcoords are between 0.0f and 1.0f.
+ */
 struct SMESH
 {
     unsigned int    m_VertexSize;   ///< Number of vertex in the arrays

include/plugins/3dapi/ifsg_api.h

@@ -41,8 +41,7 @@ struct S3D_POINT;
 namespace S3D
 {
     /**
-     * Function GetLibVersion retrieves version information of the
+     * Retrieve version information of the kicad_3dsg library.
-     * kicad_3dsg library
      */
     SGLIB_API void GetLibVersion( unsigned char* Major, unsigned char* Minor,
                                   unsigned char* Patch, unsigned char* Revision ) noexcept;
@@ -55,14 +54,12 @@ namespace S3D
     SGLIB_API void AssociateSGNodeWrapper( SGNODE* aObject, SGNODE** aRefPtr );
 
     /**
-     * Function CalcTriNorm
+     * Return the normal vector of a triangle described by vertices p1, p2, p3.
-     * returns the normal vector of a triangle described by vertices p1, p2, p3
      */
     SGLIB_API SGVECTOR CalcTriNorm( const SGPOINT& p1, const SGPOINT& p2, const SGPOINT& p3 );
 
     /**
-     * Function WriteCache
+     * Write the SGNODE tree to a binary cache file.
-     * writes the SGNODE tree to a binary cache file
      *
      * @param aFileName is the name of the file to write
      * @param overwrite must be set to true to overwrite an existing file
@@ -73,8 +70,7 @@ namespace S3D
         const char* aPluginInfo );
 
     /**
-     * Function ReadCache
+     * Read a binary cache file and creates an SGNODE tree.
-     * reads a binary cache file and creates an SGNODE tree
      *
      * @param aFileName is the name of the binary cache file to be read
      * @return NULL on failure, on success a pointer to the top level SCENEGRAPH node;
@@ -85,8 +81,7 @@ namespace S3D
         bool (*aTagCheck)( const char*, void* ) );
 
     /**
-     * Function WriteVRML
+     * Write out the given node and its subnodes to a VRML2 file.
-     * writes out the given node and its subnodes to a VRML2 file
      *
      * @param filename is the name of the output file
      * @param overwrite should be set to true to overwrite an existing VRML file
@@ -122,27 +117,25 @@ namespace S3D
     //    classes which have been created solely for the assembly output
 
     /**
-     * Function ResetNodeIndex
+     * Reset the global SG* class indices.
-     * resets the global SG* class indices
      *
      * @param aNode may be any valid SGNODE
      */
     SGLIB_API void ResetNodeIndex( SGNODE* aNode );
 
     /**
-     * Function RenameNodes
+     * Rename a node and all children nodes based on the current values of the global SG*
-     * renames a node and all children nodes based on the current
+     * class indices.
-     * values of the global SG* class indices
      *
      * @param aNode is a top level node
      */
     SGLIB_API void RenameNodes( SGNODE* aNode );
 
     /**
-     * Function DestroyNode
+     * Delete the given SG* class node.
-     * deletes the given SG* class node. This function makes it possible
+     *
-     * to safely delete an SG* node without associating the node with
+     * This function makes it possible to safely delete an SG* node without associating the
-     * its corresponding IFSG* wrapper.
+     * node with its corresponding IFSG* wrapper.
      */
     SGLIB_API void DestroyNode( SGNODE* aNode ) noexcept;
 
@@ -150,48 +143,40 @@ namespace S3D
     // of data structures for rendering
 
     /**
-     * Function GetModel
+     * Create an #S3DMODEL representation of \a aNode (raw data, no transforms).
-     * creates an S3DMODEL representation of aNode (raw data, no transforms)
      *
-     * @param aNode is the node to be transcribed into an S3DMODEL representation
+     * @param aNode is the node to be transcribed into an #S3DMODEL representation
-     * @return an S3DMODEL representation of aNode on success, otherwise NULL
+     * @return an #S3DMODEL representation of aNode on success, otherwise NULL
      */
     SGLIB_API S3DMODEL* GetModel( SCENEGRAPH* aNode );
 
     /**
-     * Function Destroy3DModel
+     * Free memory used by an S3DMODEL structure and sets the pointer to the structure to NULL.
-     * frees memory used by an S3DMODEL structure and sets the pointer to
-     * the structure to NULL
      */
     SGLIB_API void Destroy3DModel( S3DMODEL** aModel );
 
     /**
-     * Function Free3DModel
+     * Free memory used internally by an #S3DMODEL structure.
-     * frees memory used internally by an S3DMODEL structure
      */
     SGLIB_API void Free3DModel( S3DMODEL& aModel );
 
     /**
-     * Function Free3DMesh
+     * Free memory used internally by an #SMESH structure.
-     * frees memory used internally by an SMESH structure
      */
     SGLIB_API void Free3DMesh( SMESH& aMesh );
 
     /**
-     * Function New3DModel
+     * Create and initialize an #S3DMODEL structure.
-     * creates and initializes an S3DMODEL struct
      */
     SGLIB_API S3DMODEL* New3DModel( void );
 
     /**
-     * Function Init3DMaterial
+     * Initializes an #SMATERIAL structure.
-     * initializes an SMATERIAL struct
      */
     SGLIB_API void Init3DMaterial( SMATERIAL& aMat );
 
     /**
-     * Function Init3DMesh
+     * Create and initialize an #SMESH structure.
-     * creates and initializes an SMESH struct
      */
     SGLIB_API void Init3DMesh( SMESH& aMesh );
 }

include/plugins/3dapi/ifsg_colors.h

@@ -36,8 +36,7 @@
 
 
 /**
- * IFSG_COLORS
+ * The wrapper for #SGCOLORS.
- * is the wrapper for SGCOLORS
  */
 class SGLIB_API IFSG_COLORS : public IFSG_NODE
 {

include/plugins/3dapi/ifsg_coordindex.h

@@ -35,8 +35,7 @@
 
 
 /**
- * IFSG_COORDINDEX
+ * The wrapper for #SGCOORDINDEX.
- * is the wrapper for SGCOORDINDEX
  */
 class SGLIB_API IFSG_COORDINDEX : public IFSG_INDEX
 {

include/plugins/3dapi/ifsg_coords.h

@@ -34,8 +34,7 @@
 
 
 /**
- * IFSG_COORDS
+ * The wrapper for #SGCOORDS.
- * is the wrapper for SGCOORDS
  */
 class SGLIB_API IFSG_COORDS : public IFSG_NODE
 {

include/plugins/3dapi/ifsg_faceset.h

@@ -34,8 +34,7 @@
 
 
 /**
- * IFSG_FACESET
+ * The wrapper for the #SGFACESET class.
- * is the wrapper for the SGFACESET class
  */
 class SGLIB_API IFSG_FACESET : public IFSG_NODE
 {

include/plugins/3dapi/ifsg_index.h

@@ -35,8 +35,7 @@
 
 
 /**
- * IFSG_INDEX
+ * The wrapper for SGINDEX.
- * is the wrapper for SGINDEX
  */
 class SGLIB_API IFSG_INDEX : public IFSG_NODE
 {
@@ -50,20 +49,18 @@ public:
     bool GetIndices( size_t& nIndices, int*& aIndexList );
 
     /**
-     * Function SetIndices
+     * Set the number of indices and creates a copy of the given index data.
-     * sets the number of indices and creates a copy of the given index data.
      *
-     * @param nIndices [in] the number of indices to be stored
+     * @param nIndices is the number of indices to be stored.
-     * @param aIndexList [in] the index data
+     * @param aIndexList [in] is the index data.
      */
     bool SetIndices( size_t nIndices, int* aIndexList );
 
 
     /**
-     * Function AddIndex
+     * Add a single index to the list.
-     * adds a single index to the list
      *
-     * @param aIndex is the new index to add
+     * @param aIndex is the new index to add.
      */
     bool AddIndex( int aIndex );
 };

include/plugins/3dapi/ifsg_node.h

@@ -26,19 +26,6 @@
  * defines the wrapper of the base class SG_NODE
  */
 
-/*
- * NOTES:
- * 1. The IFSG wrapper classes shall be aimed at creating a VRML-like
- *    intermediate scenegraph representation. Although objects are
- *    readily created and added to the structure, no provision shall
- *    be made to inspect the structures in detail. For example the
- *    SCENEGRAPH class may contain various SGSHAPE and SCENEGRAPH
- *    nodes but there shall be no provision to extract those nodes.
- *    This was done because in principle all the detailed data shall
- *    only be handled within the SG* classes and only data processed
- *    via GetRenderData() shall be available via the wrappers.
- */
-
 #ifndef IFSG_NODE_H
 #define IFSG_NODE_H
 
@@ -48,8 +35,15 @@
 class SGNODE;
 
 /**
- * IFSG_NODE
+ * The base class of all DLL-safe Scene Graph nodes.
- * represents the base class of all DLL-safe Scene Graph nodes
+ *
+ * @note The IFSG wrapper classes shall be aimed at creating a VRML-like intermediate scenegraph
+ *       representation. Although objects are readily created and added to the structure, no
+ *       provision shall be made to inspect the structures in detail. For example the #SCENEGRAPH
+ *       class may contain various #SGSHAPE and #SCENEGRAPH nodes but there shall be no provision
+ *       to extract those nodes.  This was done because in principle all the detailed data shall
+ *       only be handled within the SG* classes and only data processed via GetRenderData() shall
+ *       be available via the wrappers.
  */
 class SGLIB_API IFSG_NODE
 {
@@ -65,101 +59,89 @@ public:
     IFSG_NODE& operator= ( const IFSG_NODE& ) = delete;
 
     /**
-     * Function Destroy
+     * Delete the object held by this wrapper.
-     * deletes the object held by this wrapper
      */
     void Destroy( void );
 
     /**
-     * Function Attach
+     * Associate a given SGNODE* with this wrapper.
-     * associates a given SGNODE* with this wrapper
      */
     virtual bool Attach( SGNODE* aNode ) = 0;
 
     /**
-     * Function NewNode
+     * Create a new node to associate with this wrapper.
-     * creates a new node to associate with this wrapper
      */
     virtual bool NewNode( SGNODE* aParent ) = 0;
     virtual bool NewNode( IFSG_NODE& aParent ) = 0;
 
     /**
-     * Function GetRawPtr()
+     * Return the raw internal SGNODE pointer.
-     * returns the raw internal SGNODE pointer
      */
     SGNODE* GetRawPtr( void ) noexcept;
 
     /**
-     * Function GetNodeType
+     * Return the type of this node instance.
-     * returns the type of this node instance
      */
     S3D::SGTYPES GetNodeType( void ) const;
 
     /**
-     * Function GetParent
+     * Return a pointer to the parent SGNODE of this object or NULL if the object has no
-     * returns a pointer to the parent SGNODE of this object
+     * parent (ie. top level transform).
-     * or NULL if the object has no parent (ie. top level transform).
      */
     SGNODE* GetParent( void ) const;
 
     /**
-     * Function SetParent
+     * Set the parent SGNODE of this object.
-     * sets the parent SGNODE of this object.
      *
-     * @param aParent [in] is the desired parent node
+     * @param aParent [in] is the desired parent node.
-     * @return true if the operation succeeds; false if
+     * @return true if the operation succeeds; false if the given node is not allowed to be a
-     * the given node is not allowed to be a parent to
+     *              parent to the derived object.
-     * the derived object
      */
     bool SetParent( SGNODE* aParent );
 
     /**
-     * Function GetName
+     * Return a pointer to the node name (NULL if no name assigned).
-     * returns a pointer to the node name (NULL if no name assigned)
      */
     const char* GetName( void );
 
     /**
-     * Function SetName
+     * Set the node's name.
-     * sets the node's name; if the pointer passed is NULL
-     * then the node's name is erased
      *
-     * @return true on success
+     * If the pointer passed is NULL, the node's name is erased.
+     *
+     * @return true on success.
      */
     bool SetName( const char *aName );
 
     /**
-     * Function GetNodeTypeName
+     * Return the text representation of the node type or NULL if the node somehow has an
-     * returns the text representation of the node type
+     * invalid type.
-     * or NULL if the node somehow has an invalid type
      */
     const char * GetNodeTypeName( S3D::SGTYPES aNodeType ) const;
 
     /**
-     * Function FindNode searches the tree of linked nodes and returns a
+     * Search the tree of linked nodes and returns a reference to the first node found with
-     * reference to the first node found with the given name. The reference
+     * the given name.
-     * is then typically added to another node via AddRefNode().
      *
-     * @param aNodeName is the name of the node to search for
+     * The reference is then typically added to another node via AddRefNode().
-     * @return is a valid node pointer on success, otherwise NULL
+     *
+     * @param aNodeName is the name of the node to search for.
+     * @return is a valid node pointer on success, otherwise NULL.
      */
     SGNODE* FindNode( const char *aNodeName );
 
     /**
-     * Function AddRefNode
+     * Add a reference to an existing node which is not owned by (not a child of) this node.
-     * adds a reference to an existing node which is not owned by
-     * (not a child of) this node.
      *
-     * @return true on success
+     * @return true on success.
      */
     bool AddRefNode( SGNODE* aNode );
     bool AddRefNode( IFSG_NODE& aNode );
 
     /**
-     * Function AddChildNode
+     * Add a node as a child owned by this node.
-     * adds a node as a child owned by this node.
      *
-     * @return true on success
+     * @return true on success.
      */
     bool AddChildNode( SGNODE* aNode );
     bool AddChildNode( IFSG_NODE& aNode );

include/plugins/3dapi/ifsg_normals.h

@@ -34,8 +34,7 @@
 
 
 /**
- * IFSG_NORMALS
+ * The wrapper for the #SGNORMALS class.
- * is the wrapper for the SGNORMALS class
  */
 class SGLIB_API IFSG_NORMALS : public IFSG_NODE
 {

include/plugins/3dapi/ifsg_shape.h

@@ -34,8 +34,7 @@
 
 
 /**
- * IFSG_SHAPE
+ * The wrapper for the SGSHAPE class.
- * is the wrapper for the SGSHAPE class
  */
 class SGLIB_API IFSG_SHAPE : public IFSG_NODE
 {

include/plugins/3dapi/ifsg_transform.h

@@ -34,17 +34,18 @@
 
 
 /**
- * IFSG_TRANSFORM
+ * The wrapper for the VRML compatible #TRANSFORM block class #SCENEGRAPH.
- * is the wrapper for the VRML compatible TRANSFORM block class SCENEGRAPH
  */
 class SGLIB_API IFSG_TRANSFORM : public IFSG_NODE
 {
 public:
+    /**
+     * @note IFSG_TRANSFORM( IFSG_NODE& aParent ) does not exist since a transform may own
+     *       another transform and that construct invites accidental misuse of the copy
+     *       constructor./
+     */
     IFSG_TRANSFORM( bool create );
     IFSG_TRANSFORM( SGNODE* aParent );
-    // note: IFSG_TRANSFORM( IFSG_NODE& aParent ) does not exist
-    // since a transform may own another transform and that construct
-    // invites accidental misuse of the copy constructor
 
     bool Attach( SGNODE* aNode ) override;
     bool NewNode( SGNODE* aParent ) override;

include/plugins/kicad_plugin.h

@@ -43,70 +43,64 @@
 #endif
 
 /**
- * Function GetKicadPluginClass
+ * Return the name of the implemented plugin class, for example 3DPLUGIN.
- * returns the name of the implemented plugin class; for
+ *
- * example 3DPLUGIN. This should be implemented in a source
+ * This should be implemented in a source module which is compiled as part of every implementation
- * module which is compiled as part of every implementation
  * of a specific plugin class.
  *
- * @return is the NULL-terminated UTF-8 string representing the
+ * @return is the NULL-terminated UTF-8 string representing the plugin class.
- * plugin class
  */
 KICAD_PLUGIN_EXPORT char const* GetKicadPluginClass( void );
 
 /**
- * Function GetClassVersion
+ * Retrieve the version of the Plugin Class.
- * retrieves the version of the Plugin Class. This value is used to
- * ensure API compatibility of a plugin as per typical practice. This must
- * be implemented in a source module which is compiled as part of every
- * implementation of a specific plugin class
  *
- * @param Major will hold the Plugin Class Major version
+ * This value is used to ensure API compatibility of a plugin as per typical practice. This must
- * @param Minor will hold the Plugin Class Minor version
+ * be implemented in a source module which is compiled as part of every implementation of a
- * @param Revision will hold the Plugin Class Revision
+ * specific plugin class.
- * @param Patch will hold the Plugin Class Patch level
+ *
+ * @param Major will hold the Plugin Class Major version.
+ * @param Minor will hold the Plugin Class Minor version.
+ * @param Revision will hold the Plugin Class Revision.
+ * @param Patch will hold the Plugin Class Patch level.
  */
-KICAD_PLUGIN_EXPORT void GetClassVersion( unsigned char* Major,
+KICAD_PLUGIN_EXPORT void GetClassVersion( unsigned char* Major, unsigned char* Minor,
-    unsigned char* Minor, unsigned char* Patch, unsigned char* Revision );
+                                          unsigned char* Patch, unsigned char* Revision );
 
 /**
- * Function CheckClassVersion
+ * Return true if the class version reported by the Plugin Loader is compatible with the specific
- * returns true if the class version reported by the Plugin Loader
+ * implementation of a plugin.
- * is compatible with the specific implementation of a plugin.
+ *
- * This function must be defined by each specific plugin and it is
+ * This function must be defined by each specific plugin and it is the plugin developer's
- * the plugin developer's responsibility to ensure that the Plugin
+ * responsibility to ensure that the Plugin is in fact compatible with the Plugin Loader. The
- * is in fact compatible with the Plugin Loader. The Plugin Loader
+ * Plugin Loader shall reject any Plugin with a different Major number regardless of the return
- * shall reject any Plugin with a different Major number regardless
+ * value of this function.
- * of the return value of this function.
  */
-KICAD_PLUGIN_EXPORT bool CheckClassVersion( unsigned char Major,
+KICAD_PLUGIN_EXPORT bool CheckClassVersion( unsigned char Major, unsigned char Minor,
-    unsigned char Minor, unsigned char Patch, unsigned char Revision );
+                                            unsigned char Patch, unsigned char Revision );
 
 /**
- * Function GetKicadPluginName
+ * Return the name of the plugin instance, for example IDFv3.
- * returns the name of the plugin instance; for example IDFv3.
- * This string may be used to check for name conflicts or to
- * display informational messages about loaded plugins. This method
- * must be implemented in specific instantiations of a plugin class.
  *
- * @return is the NULL-terminated UTF-8 string representing the
+ * This string may be used to check for name conflicts or to display informational messages about
- * plugin name
+ * loaded plugins. This method must be implemented in specific instantiations of a plugin class.
+ *
+ * @return is the NULL-terminated UTF-8 string representing the plugin name.
  */
 KICAD_PLUGIN_EXPORT const char* GetKicadPluginName( void );
 
 
 /**
- * Function GetPluginVersion
+ * Retrieve the version of the instantiated plugin for informational purposes.
- * retrieves the version of the instantiated plugin for informational
- * purposes. Do not confuse this with GetClassVersion which is used to
- * determine API compatibility.
  *
- * @param Major will hold the Plugin Major version
+ * Do not confuse this with GetClassVersion which is used to determine API compatibility.
- * @param Minor will hold the Plugin Minor version
+ *
- * @param Patch will hold the Plugin Patch level
+ * @param Major will hold the Plugin Major version.
- * @param Revision will hold the Plugin Revision
+ * @param Minor will hold the Plugin Minor version.
+ * @param Patch will hold the Plugin Patch level.
+ * @param Revision will hold the Plugin Revision.
  */
-KICAD_PLUGIN_EXPORT void GetPluginVersion( unsigned char* Major,
+KICAD_PLUGIN_EXPORT void GetPluginVersion( unsigned char* Major, unsigned char* Minor,
-    unsigned char* Minor, unsigned char* Patch, unsigned char* Revision );
+                                           unsigned char* Patch, unsigned char* Revision );
 
 #endif  // KICAD_PLUGIN_H

include/preview_items/arc_assistant.h

@@ -30,49 +30,52 @@
 
 namespace KIGFX
 {
+
 namespace PREVIEW
 {
-    /**
+
-     * Represents an assistant draw when interactively drawing an arc on a canvas.
+/**
-     */
+ * Represents an assistant draw when interactively drawing an arc on a canvas.
-    class ARC_ASSISTANT : public EDA_ITEM
+ */
+class ARC_ASSISTANT : public EDA_ITEM
+{
+public:
+    ARC_ASSISTANT( const ARC_GEOM_MANAGER& aManager,
+                   const EDA_IU_SCALE& aIuScale,
+                   EDA_UNITS aUnits );
+
+    const BOX2I ViewBBox() const override;
+
+    std::vector<int> ViewGetLayers() const override
     {
-    public:
+        return { LAYER_SELECT_OVERLAY,  // Assistant graphics
-        ARC_ASSISTANT( const ARC_GEOM_MANAGER& aManager,
+            LAYER_GP_OVERLAY };     // Drop shadows
-                       const EDA_IU_SCALE& aIuScale,
+    }
-                       EDA_UNITS aUnits );
 
-        const BOX2I ViewBBox() const override;
+    /**
-
+     * Draw the assistance (with reference to the construction manager
-        std::vector<int> ViewGetLayers() const override
+     */
-        {
+    void ViewDraw( int aLayer, KIGFX::VIEW* aView ) const override final;
-            return { LAYER_SELECT_OVERLAY,  // Assistant graphics
-                     LAYER_GP_OVERLAY };     // Drop shadows
-        }
-
-        /**
-         * Draw the assistance (with reference to the construction manager
-         */
-        void ViewDraw( int aLayer, KIGFX::VIEW* aView ) const override final;
 
 #if defined( DEBUG )
-        void Show( int x, std::ostream& st ) const override
+    void Show( int x, std::ostream& st ) const override
-        {
+    {
-        }
+    }
 #endif
 
-        wxString GetClass() const override
+    wxString GetClass() const override
-        {
+    {
-            return "ARC_ASSISTANT";
+        return "ARC_ASSISTANT";
-        }
+    }
 
-        void SetUnits( EDA_UNITS aUnits ) { m_units = aUnits; }
+    void SetUnits( EDA_UNITS aUnits ) { m_units = aUnits; }
+
+private:
+    const ARC_GEOM_MANAGER& m_constructMan;
+    const EDA_IU_SCALE&     m_iuScale;
+    EDA_UNITS               m_units;
+};
 
-    private:
-        const ARC_GEOM_MANAGER& m_constructMan;
-        const EDA_IU_SCALE&     m_iuScale;
-        EDA_UNITS               m_units;
-    };
 } // namespace PREVIEW
 } // namespace KIGFX
 

include/preview_items/arc_geom_manager.h

@@ -30,7 +30,6 @@
 namespace KIGFX {
 namespace PREVIEW {
 
-
 /**
  * Manage the construction of a circular arc though sequential setting of critical points:
  * center, arc start and arc end. The manager is driven by setting cursor points, which
@@ -133,6 +132,7 @@ private:
     bool m_angleSnap = false;
     bool m_directionLocked = false;
 };
+
 }       // PREVIEW
 }       // KIGFX
 

include/preview_items/bezier_geom_manager.h

@@ -32,8 +32,7 @@ namespace KIGFX
 namespace PREVIEW
 {
 
-
+/**
-    /**
  * Manage the construction of a bezier through a series of steps.
  *
  * See also @ref KIGFX::PREVIEW::ARC_GEOM_MANAGER.
@@ -41,62 +40,63 @@ namespace PREVIEW
  * Interfaces are provided to return both arc geometry (can be used to set up real beziers on
  * PCBs, for example) as well as important control points for informational overlays.
  */
-    class BEZIER_GEOM_MANAGER : public MULTISTEP_GEOM_MANAGER
+class BEZIER_GEOM_MANAGER : public MULTISTEP_GEOM_MANAGER
+{
+public:
+    BEZIER_GEOM_MANAGER() {}
+
+    enum BEZIER_STEPS
     {
-    public:
+        SET_START = 0, ///< Waiting to lock in the start point
-        BEZIER_GEOM_MANAGER() {}
+        SET_CONTROL1,  ///< Waiting to lock in the first control point
+        SET_END,       ///< Waiting to lock in the end point
+        SET_CONTROL2,  ///< Waiting to lock in the second control point
+        COMPLETE
+    };
 
-        enum BEZIER_STEPS
+    int getMaxStep() const override { return COMPLETE; }
-        {
-            SET_START = 0, ///< Waiting to lock in the start point
-            SET_CONTROL1,  ///< Waiting to lock in the first control point
-            SET_END,       ///< Waiting to lock in the end point
-            SET_CONTROL2,  ///< Waiting to lock in the second control point
-            COMPLETE
-        };
 
-        int getMaxStep() const override { return COMPLETE; }
+    /**
-
-        /**
      * Get the current step the manager is on (useful when drawing
      * something depends on the current state)
      */
-        BEZIER_STEPS GetStep() const { return static_cast<BEZIER_STEPS>( getStep() ); }
+    BEZIER_STEPS GetStep() const { return static_cast<BEZIER_STEPS>( getStep() ); }
 
-        bool acceptPoint( const VECTOR2I& aPt ) override;
+    bool acceptPoint( const VECTOR2I& aPt ) override;
 
-        /*
+    /*
      * Geometry query interface - used by clients of the manager
      */
 
-        ///< Get the center point of the arc (valid when state > SET_ORIGIN)
+    ///< Get the center point of the arc (valid when state > SET_ORIGIN)
-        VECTOR2I GetStart() const;
+    VECTOR2I GetStart() const;
 
-        ///< Get the coordinates of the arc start
+    ///< Get the coordinates of the arc start
-        VECTOR2I GetControlC1() const;
+    VECTOR2I GetControlC1() const;
-        VECTOR2I GetControlC2() const;
+    VECTOR2I GetControlC2() const;
 
-        ///< Get the coordinates of the arc end point
+    ///< Get the coordinates of the arc end point
-        VECTOR2I GetEnd() const;
+    VECTOR2I GetEnd() const;
 
-    private:
+private:
-        /*
+    /*
      * Point acceptor functions
      */
 
-        ///< Set the center point of the arc
+    ///< Set the center point of the arc
-        bool setStart( const VECTOR2I& aOrigin );
+    bool setStart( const VECTOR2I& aOrigin );
-        bool setControlC1( const VECTOR2I& aControl );
+    bool setControlC1( const VECTOR2I& aControl );
-        bool setEnd( const VECTOR2I& aCursor );
+    bool setEnd( const VECTOR2I& aCursor );
-        bool setControlC2( const VECTOR2I& aControl );
+    bool setControlC2( const VECTOR2I& aControl );
 
-        /*
+    /*
      * Bezier geometry
      */
-        VECTOR2I m_start;
+    VECTOR2I m_start;
-        VECTOR2I m_controlC1;
+    VECTOR2I m_controlC1;
-        VECTOR2I m_end;
+    VECTOR2I m_end;
-        VECTOR2I m_controlC2;
+    VECTOR2I m_controlC2;
-    };
+};
+
 } // namespace PREVIEW
 } // namespace KIGFX

include/preview_items/draw_context.h

@@ -34,100 +34,100 @@ class VIEW;
 
 namespace PREVIEW
 {
+/**
+ * A KIGFX::PREVIEW::DRAW_CONTEXT is a wrapper around a GAL and some other
+ * settings that makes it easy to draw preview items consistently.
+ *
+ * This class provides some graphical items that are often used by preview
+ * items. Complex items can be composed from these.
+ */
+class DRAW_CONTEXT
+{
+public:
+    DRAW_CONTEXT( KIGFX::VIEW& aView );
+
     /**
-     * A KIGFX::PREVIEW::DRAW_CONTEXT is a wrapper around a GAL and some other
+     * Draw a preview circle on the current layer.
-     * settings that makes it easy to draw preview items consistently.
      *
-     * This class provides some graphical items that are often used by preview
+     * @param aOrigin circle origin.
-     * items. Complex items can be composed from these.
+     * @param aRad    circle radius.
+     * @param aDeEmphasised draw the circle de-emphasized.
      */
-    class DRAW_CONTEXT
+    void DrawCircle( const VECTOR2I& aOrigin, double aRad, bool aDeEmphasised );
-    {
-    public:
-        DRAW_CONTEXT( KIGFX::VIEW& aView );
 
-        /**
+    /**
-         * Draw a preview circle on the current layer
+     * Draw a dashed preview circle on the current layer.
-         *
+     *
-         * @param aOrigin circle origin
+     * @param aOrigin       circle origin.
-         * @param aRad    circle radius
+     * @param aRad          circle radius.
-         * @param aDeEmphasised draw the circle de-emphasised
+     * @param aStepAngle    dash step angle.
-         */
+     * @param aFillAngle    dash fill angle.
-        void DrawCircle( const VECTOR2I& aOrigin, double aRad, bool aDeEmphasised );
+     * @param aDeEmphasised draw the circle de-emphasized.
+     */
+    void DrawCircleDashed( const VECTOR2I& aOrigin, double aRad, double aStepAngle,
+                           double aFillAngle, bool aDeEmphasised );
 
-        /**
+    /**
-         * Draw a dashed preview circle on the current layer
+     * Draw a simple line on the current layer.
-         *
+     *
-         * @param aOrigin       circle origin
+     * @param aStart        line start point.
-         * @param aRad          circle radius
+     * @param aEnd          line end point.
-         * @param aStepAngle    dash step angle
+     * @param aDeEmphasised draw the line de-.
-         * @param aFillAngle    dash fill angle
+     */
-         * @param aDeEmphasised draw the circle de-emphasised
+    void DrawLine( const VECTOR2I& aStart, const VECTOR2I& aEnd, bool aDeEmphasised );
-         */
-        void DrawCircleDashed( const VECTOR2I& aOrigin, double aRad, double aStepAngle,
-                               double aFillAngle, bool aDeEmphasised );
 
-        /**
+    /**
-         * Draw a simple line on the current layer.
+     * Draw a dashed line on the current layer.
-         *
+     *
-         * @param aStart        line start point
+     * @param aStart        line start point.
-         * @param aEnd          line end point
+     * @param aEnd          line end point.
-         * @param aDeEmphasised draw the line de-emphasised
+     * @param aDashStep     dash step distance.
-         */
+     * @param aDashFill     dash fill distance.
-        void DrawLine( const VECTOR2I& aStart, const VECTOR2I& aEnd, bool aDeEmphasised );
+     * @param aDeEmphasised draw the line de-emphasized.
+     */
+    void DrawLineDashed( const VECTOR2I& aStart, const VECTOR2I& aEn, int aDashStep,
+                         int aDashFill, bool aDeEmphasised );
 
-        /**
+    /**
-         * Draw a dashed line on the current layer.
+     * Draw a straight line on the current layer, with a special highlight when
-         *
+     * the line angle is a multiple of 45 degrees.
-         * @param aStart        line start point
+     *
-         * @param aEnd          line end point
+     * @param aStart        line start point.
-         * @param aDashStep     dash step distance
+     * @param aEnd          line end point.
-         * @param aDashFill     dash fill distance
+     * @param aDeEmphasised draw the line de-emphasized.
-         * @param aDeEmphasised draw the line de-emphasised
+     */
-         */
+    void DrawLineWithAngleHighlight(
-        void DrawLineDashed( const VECTOR2I& aStart, const VECTOR2I& aEn, int aDashStep,
+            const VECTOR2I& aStart, const VECTOR2I& aEnd, bool aDeEmphasised );
-                             int aDashFill, bool aDeEmphasised );
 
-        /**
+    /**
-         * Draw a straight line on the current layer, with a special highlight when
+     * Draw an arc on the current layer, with a special highlight when
-         * the line angle is a multiple of 45 degrees.
+     * the line angle is a multiple of 45 degrees.
-         *
+     *
-         * @param aStart        line start point
+     * @param aOrigin     the arc centre.
-         * @param aEnd          line end point
+     * @param aRad        the arc radius.
-         * @param aDeEmphasised draw the line de-emphasised
+     * @param aStartAngle the arc start angle.
-         */
+     * @param aEndAngle   the arc end angle.
-        void DrawLineWithAngleHighlight(
+     */
-                const VECTOR2I& aStart, const VECTOR2I& aEnd, bool aDeEmphasised );
+    void DrawArcWithAngleHighlight( const VECTOR2I& aOrigin, double aRad, double aStartAngle,
+                                    double aEndAngle );
 
-        /**
+private:
-         * Draw an arc on the current layer, with a special highlight when
+    /**
-         * the line angle is a multiple of 45 degrees.
+     * @return the colour to use for "special" angles.
-         *
+     */
-         * @param aOrigin     the arc centre
+    COLOR4D getSpecialAngleColour() const;
-         * @param aRad        the arc radius
-         * @param aStartAngle the arc start angle
-         * @param aEndAngle   the arc end angle
-         */
-        void DrawArcWithAngleHighlight(
-                const VECTOR2I& aOrigin, double aRad, double aStartAngle, double aEndAngle );
 
-    private:
+    ///< The GAL to draw into
-        /**
+    KIGFX::GAL& m_gal;
-         * @return the colour to use for "special" angles
-         */
-        COLOR4D getSpecialAngleColour() const;
 
-        ///< The GAL to draw into
+    const KIGFX::RENDER_SETTINGS& m_render_settings;
-        KIGFX::GAL& m_gal;
 
-        const KIGFX::RENDER_SETTINGS& m_render_settings;
+    ///< The current layer to draw onto
+    GAL_LAYER_ID m_currLayer;
 
-        ///< The current layer to draw onto
+    /// The line width to use for items
-        GAL_LAYER_ID m_currLayer;
+    float m_lineWidth;
-
+};
-        /// The line width to use for items
-        float m_lineWidth;
-    };
 
 } // namespace PREVIEW
 } // namespace KIGFX

include/preview_items/item_drawing_utils.h

@@ -36,13 +36,14 @@
 
 namespace KIGFX
 {
+
 /**
-* Draw a cross at a given position.
+ * Draw a cross at a given position.
-*
+ *
-* @param aGal The graphics abstraction layer to draw with.
+ * @param aGal The graphics abstraction layer to draw with.
-* @param aPosition The position to draw the cross at.
+ * @param aPosition The position to draw the cross at.
-* @param aSize The size of the cross.
+ * @param aSize The size of the cross.
-*/
+ */
 void DrawCross( GAL& aGal, const VECTOR2I& aPosition, int aSize );
 
 /**

include/preview_items/preview_utils.h

@@ -54,8 +54,8 @@ double PreviewOverlayDeemphAlpha( bool aDeemph = true );
  * Get a formatted string showing a dimension to a sane precision with an optional prefix and
  * unit suffix.
  */
-wxString DimensionLabel( const wxString& prefix, double aVal, const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnits,
+wxString DimensionLabel( const wxString& prefix, double aVal, const EDA_IU_SCALE& aIuScale,
-                         bool aIncludeUnits = true );
+                         EDA_UNITS aUnits, bool aIncludeUnits = true );
 
 /**
  * Set the GAL glyph height to a constant scaled value, so that it always looks the same on screen.

include/preview_items/ruler_item.h

@@ -44,8 +44,8 @@ class TWO_POINT_GEOMETRY_MANAGER;
 class RULER_ITEM : public EDA_ITEM
 {
 public:
-    RULER_ITEM( const TWO_POINT_GEOMETRY_MANAGER& m_geomMgr, const EDA_IU_SCALE& aIuScale, EDA_UNITS userUnits, bool aFlipX,
+    RULER_ITEM( const TWO_POINT_GEOMETRY_MANAGER& m_geomMgr, const EDA_IU_SCALE& aIuScale,
-            bool aFlipY );
+                EDA_UNITS userUnits, bool aFlipX, bool aFlipY );
 
     ///< @copydoc EDA_ITEM::ViewBBox()
     const BOX2I ViewBBox() const override;
@@ -63,7 +63,7 @@ public:
     void SetShowEndArrowHead( bool aShow ) { m_showEndArrowHead = aShow; }
 
     /**
-     * Get the strings for the dimensions of the ruler
+     * Get the strings for the dimensions of the ruler.
      */
     wxArrayString GetDimensionStrings() const;
 
@@ -74,8 +74,9 @@ public:
 #endif
 
     /**
-     * Get class name
+     * Get class name.
-     * @return  string "RULER_ITEM"
+     *
+     * @return  string "RULER_ITEM".
      */
     wxString GetClass() const override
     {
@@ -83,9 +84,9 @@ public:
     }
 
     /**
-     * Switch the ruler units
+     * Switch the ruler units.
      *
-     * @param aUnits is the new unit system the ruler should use
+     * @param aUnits is the new unit system the ruler should use.
      */
     void SwitchUnits( EDA_UNITS aUnits ) { m_userUnits = aUnits; }
 

include/preview_items/snap_indicator.h

@@ -38,7 +38,7 @@ class SNAP_INDICATOR : public ORIGIN_VIEWITEM
 {
 public:
     SNAP_INDICATOR( const COLOR4D& aColor = COLOR4D::WHITE, int aSize = 16,
-                   const VECTOR2D& aPosition = VECTOR2D( 0, 0 ) );
+                    const VECTOR2D& aPosition = VECTOR2D( 0, 0 ) );
 
     SNAP_INDICATOR( const VECTOR2D& aPosition, EDA_ITEM_FLAGS flags );
 

include/project/project_archiver.h

@@ -37,37 +37,43 @@ public:
     ~PROJECT_ARCHIVER() = default;
 
     /**
-     * Compares the crcs of all the files in zip archive to determine whether the archives are identical
+     * Compare the CRCs of all the files in zip archive to determine whether the archives are
-     * @param aZipFileA is the full path to the first zip
+     * identical.
-     * @param aZipFileB is the full path to the second zip
+     *
-     * @param aReporter is used to report status
+     * @param aZipFileA is the full path to the first zip.
-     * @return true if the archives are identical
+     * @param aZipFileB is the full path to the second zip.
+     * @param aReporter is used to report status.
+     * @return true if the archives are identical.
      */
     static bool AreZipArchivesIdentical( const wxString& aZipFileA, const wxString& aZipFileB,
-                                        REPORTER& aReporter );
+                                         REPORTER& aReporter );
 
     /**
-     * Creates an archive of the project
+     * Create an archive of the project.
-     * @param aSrcFile is the full path to the project to be archived
+     *
-     * @param aDestFile is the full path to the zip file to be created
+     * @param aSrcFile is the full path to the project to be archived.
-     * @param aReporter is used to report status
+     * @param aDestFile is the full path to the zip file to be created.
-     * @param aVerbose controls the verbosity of reported status messages
+     * @param aReporter is used to report status.
-     * @param aIncludeExtraFiles if true will archive legacy and output files
+     * @param aVerbose controls the verbosity of reported status messages.
-     * @return true if the archive was created successfully
+     * @param aIncludeExtraFiles if true will archive legacy and output files.
+     * @return true if the archive was created successfully.
      */
     static bool Archive( const wxString& aSrcDir, const wxString& aDestFile, REPORTER& aReporter,
                          bool aVerbose = true, bool aIncludeExtraFiles = false );
 
     /**
-     * Extracts an archive of the current project over existing files
+     * Extract an archive of the current project over existing files.
-     * Warning: this will overwrite files in the project directory.  Use with care.  The caller is
+     *
+     * @warning This will overwrite files in the project directory.  Use with care.  The caller is
      * responsible for doing any reloading of state after taking this action.
-     * @param aSrcFile is the full path to the archive to extract
+     *
-     * @param aDestDir is the target directory to unarchive to
+     * @param aSrcFile is the full path to the archive to extract.
-     * @param aReporter is used to report status
+     * @param aDestDir is the target directory to unarchive to.
-     * @return true if the archive was created successfully
+     * @param aReporter is used to report status.
+     * @return true if the archive was created successfully.
      */
-    static bool Unarchive( const wxString& aSrcFile, const wxString& aDestDir, REPORTER& aReporter );
+    static bool Unarchive( const wxString& aSrcFile, const wxString& aDestDir,
+                           REPORTER& aReporter );
 };
 
 #endif // KICAD_PROJECT_ARCHIVER_H

include/settings/app_settings.h

@@ -26,18 +26,18 @@
 #include <settings/grid_settings.h>
 
 /**
- * Cross-probing behavior
+ * Cross-probing behavior.
  */
 struct KICOMMON_API CROSS_PROBING_SETTINGS
 {
-    bool on_selection;  ///< Synchronize the selection for multiple items too
+    bool on_selection;    ///< Synchronize the selection for multiple items too.
-    bool center_on_items; ///< Automatically pan to cross-probed items
+    bool center_on_items; ///< Automatically pan to cross-probed items.
-    bool zoom_to_fit;     ///< Zoom to fit items (ignored if center_on_items is off)
+    bool zoom_to_fit;     ///< Zoom to fit items (ignored if center_on_items is off).
-    bool auto_highlight;  ///< Automatically turn on highlight mode in the target frame
+    bool auto_highlight;  ///< Automatically turn on highlight mode in the target frame.
 };
 
 /**
- * Common cursor settings, available to every frame
+ * Common cursor settings, available to every frame.
  */
 struct KICOMMON_API CURSOR_SETTINGS
 {
@@ -55,7 +55,7 @@ enum class ARC_EDIT_MODE
 };
 
 /**
-* Stores the window positioning/state
+* Store the window positioning/state.
 */
 struct KICOMMON_API WINDOW_STATE
 {
@@ -68,7 +68,7 @@ struct KICOMMON_API WINDOW_STATE
 };
 
 /**
- * Stores the common settings that are saved and loaded for each window / frame
+ * Store the common settings that are saved and loaded for each window / frame.
  */
 struct KICOMMON_API WINDOW_SETTINGS
 {
@@ -119,8 +119,8 @@ public:
     struct GRAPHICS
     {
         int   canvas_type;
-        float highlight_factor;         ///< How much to brighten highlighted objects by
+        float highlight_factor;         ///< How much to brighten highlighted objects by.
-        float select_factor;            ///< How much to brighten selected objects by
+        float select_factor;            ///< How much to brighten selected objects by.
     };
 
     struct COLOR_PICKER
@@ -130,20 +130,20 @@ public:
 
     struct LIB_TREE
     {
-        std::vector<wxString> columns;         ///< Ordered list of visible columns in the tree
+        std::vector<wxString> columns;         ///< Ordered list of visible columns in the tree.
-        std::map<wxString, int> column_widths; ///< Column widths, keyed by header name
+        std::map<wxString, int> column_widths; ///< Column widths, keyed by header name.
-        std::vector<wxString>   open_libs;     ///< list of libraries the user has open in the tree
+        std::vector<wxString>   open_libs;     ///< list of libraries the user has open in the tree.
     };
 
     struct PRINTING
     {
-        bool             background;    ///< Whether or not to print background color
+        bool             background;    ///< Whether or not to print background color.
-        bool             monochrome;    ///< Whether or not to print in monochrome
+        bool             monochrome;    ///< Whether or not to print in monochrome.
-        double           scale;         ///< Printout scale
+        double           scale;         ///< Printout scale.
-        bool             use_theme;     ///< If false, display color theme will be used
+        bool             use_theme;     ///< If false, display color theme will be used.
-        wxString         color_theme;   ///< Color theme to use for printing
+        wxString         color_theme;   ///< Color theme to use for printing.
-        bool             title_block;   ///< Whether or not to print title block
+        bool             title_block;   ///< Whether or not to print title block.
-        std::vector<int> layers;        ///< List of enabled layers for printing
+        std::vector<int> layers;        ///< List of enabled layers for printing.
     };
 
     struct SYSTEM
@@ -154,13 +154,15 @@ public:
         int                   units;
         int                   last_metric_units;
         int                   last_imperial_units;
-        /// Stored value for "show import issues" when importing non-KiCad designs to this application
+
+        /// Stored value for "show import issues" when importing non-KiCad designs to this
+        /// application.
         bool                  show_import_issues;
     };
 
     struct PLUGINS
     {
-        /// Ordered list of plugin actions mapped to whether or not they are shown in the toolbar
+        /// Ordered list of plugin actions mapped to whether or not they are shown in the toolbar.
         std::vector<std::pair<wxString, bool>> actions;
     };
 
@@ -193,39 +195,41 @@ public:
 
     WINDOW_SETTINGS m_Window;
 
-    /// Active color theme name
+    /// Active color theme name.
     wxString m_ColorTheme;
 
 
-    ///! Local schema version for common app settings
+    ///! Local schema version for common app settings.
     int m_appSettingsSchemaVersion;
 
 protected:
 
     virtual std::string getLegacyFrameName() const { return std::string(); }
 
-    ///! Migrates the find/replace history string lists
+    ///! Migrates the find/replace history string list.s
     void migrateFindReplace( wxConfigBase* aCfg );
 
     /**
-     * Migrates legacy window settings into the JSON document
+     * Migrate legacy window settings into the JSON document.
+     *
      * @param aCfg is the wxConfig object to read from
      * @param aFrameName is the prefix for window settings in the legacy config file
      * @param aJsonPath is the prefix for storing window settings in the JSON file
      * @return true if all settings were migrated
      */
     bool migrateWindowConfig( wxConfigBase* aCfg, const std::string& aFrameName,
-            const std::string& aJsonPath );
+                              const std::string& aJsonPath );
 
     /**
-     * Adds parameters for the given window object
+     * Add parameters for the given window object.
-     * @param aWindow is the target window settings object
+     *
-     * @param aJsonPath is the path to read parameters from
+     * @param aWindow is the target window settings object.
+     * @param aJsonPath is the path to read parameters from.
      */
     void addParamsForWindow( WINDOW_SETTINGS* aWindow, const std::string& aJsonPath );
 
     /**
-     * Migrates the library tree width setting from a single column (Item) to multi-column
+     * Migrate the library tree width setting from a single column (Item) to multi-column.
      */
     bool migrateLibTreeWidth();
 };

include/settings/settings_manager.h

@@ -62,9 +62,10 @@ public:
     void SetKiway( KIWAY* aKiway ) { m_kiway = aKiway; }
 
     /**
-     * Takes ownership of the pointer passed in
+     * Take ownership of the pointer passed in.
-     * @param aSettings is a settings object to register
+     *
-     * @return a handle to the owned pointer
+     * @param aSettings is a settings object to register.
+     * @return a handle to the owned pointer.
      */
     template<typename T>
     T* RegisterSettings( T* aSettings, bool aLoadNow = true )
@@ -81,21 +82,23 @@ public:
     void Save( JSON_SETTINGS* aSettings );
 
     /**
-     * If the given settings object is registered, save it to disk and unregister it
+     * If the given settings object is registered, save it to disk and unregister it.
+     *
      * @param aSettings is the object to release
      */
     void FlushAndRelease( JSON_SETTINGS* aSettings, bool aSave = true );
 
     /**
-     * Returns a handle to the a given settings by type
+     * Return a handle to the a given settings by type.
+     *
      * If the settings have already been loaded, returns the existing pointer.
      * If the settings have not been loaded, creates a new object owned by the
      * settings manager and returns a pointer to it.
      *
-     * @tparam T is a type derived from APP_SETTINGS_BASE
+     * @tparam T is a type derived from APP_SETTINGS_BASE.
      * @param aFilename is used to find the correct settings under clang (where
-     *                  RTTI doesn't work across compile boundaries)
+     *                  RTTI doesn't work across compile boundaries).
-     * @return a pointer to a loaded settings object
+     * @return a pointer to a loaded settings object.
      */
     template<typename T>
     T* GetAppSettings( const wxString& aFilename )
@@ -138,11 +141,12 @@ public:
     }
 
     /**
-     * Retrieves a color settings object that applications can read colors from.
+     * Retrieve a color settings object that applications can read colors from.
+     *
      * If the given settings file cannot be found, returns the default settings.
      *
-     * @param aName is the name of the color scheme to load
+     * @param aName is the name of the color scheme to load.
-     * @return a loaded COLOR_SETTINGS object
+     * @return a loaded COLOR_SETTINGS object.
      */
     COLOR_SETTINGS* GetColorSettings( const wxString& aName = "user" );
 
@@ -162,45 +166,51 @@ public:
     }
 
     /**
-     * Safely saves a COLOR_SETTINGS to disk, preserving any changes outside the given namespace.
+     * Safely save a #COLOR_SETTINGS to disk, preserving any changes outside the given namespace.
      *
      * A color settings namespace is one of the top-level JSON objects like "board", etc.
      * This will perform a read-modify-write
      *
-     * @param aSettings is a pointer to a valid COLOR_SETTINGS object managed by SETTINGS_MANAGER
+     * @param aSettings is a pointer to a valid COLOR_SETTINGS object managed by SETTINGS_MANAGER.
-     * @param aNamespace is the namespace of settings to save
+     * @param aNamespace is the namespace of settings to save.
      */
     void SaveColorSettings( COLOR_SETTINGS* aSettings, const std::string& aNamespace = "" );
 
     /**
-     * Registers a new color settings object with the given filename
+     * Register a new color settings object with the given filename.
-     * @param aFilename is the location to store the new settings object
+     *
-     * @return a pointer to the new object
+     * @param aFilename is the location to store the new settings object.
+     * @return a pointer to the new object.
      */
     COLOR_SETTINGS* AddNewColorSettings( const wxString& aFilename );
 
     /**
-     * Returns a color theme for storing colors migrated from legacy (5.x and earlier) settings,
+     * Return a color theme for storing colors migrated from legacy (5.x and earlier) settings,
-     * creating the theme if necessary.  This theme will be called "user.json" / "User".
+     * creating the theme if necessary.
-     * @return the color settings to be used for migrating legacy settings
+     *
+     * This theme will be called "user.json" / "User".
+     *
+     * @return the color settings to be used for migrating legacy settings.
      */
     COLOR_SETTINGS* GetMigratedColorSettings();
 
     /**
-     * Retrieves the common settings shared by all applications
+     * Retrieve the common settings shared by all applications.
-     * @return a pointer to a loaded COMMON_SETTINGS
+     *
+     * @return a pointer to a loaded #COMMON_SETTINGS.
      */
     COMMON_SETTINGS* GetCommonSettings() const { return m_common_settings; }
 
     /**
-     * Returns the path a given settings file should be loaded from / stored to.
+     * Return the path a given settings file should be loaded from / stored to.
-     * @param aSettings is the settings object
+     *
-     * @return a path based on aSettings->m_location
+     * @param aSettings is the settings object.
+     * @return a path based on aSettings->m_location.
      */
     wxString GetPathForSettingsFile( JSON_SETTINGS* aSettings );
 
     /**
-     * Handles the initialization of the user settings directory and migration from previous
+     * Handle the initialization of the user settings directory and migration from previous
      * KiCad versions as needed.
      *
      * This method will check for the existence of the user settings path for this KiCad version.
@@ -208,179 +218,201 @@ public:
      *
      * If that directory is empty or does not exist, the migration wizard will be launched, which
      * will give users the option to migrate settings from a previous KiCad version (if one is
-     * found), manually specify a directory to migrate fromm, or start with default settings.
+     * found), manually specify a directory to migrate from, or start with default settings.
      *
-     * @return true if migration was successful or not necessary, false otherwise
+     * @return true if migration was successful or not necessary, false otherwise.
      */
     bool MigrateIfNeeded();
 
     /**
-     * Helper for DIALOG_MIGRATE_SETTINGS to specify a source for migration
+     * Helper for #DIALOG_MIGRATE_SETTINGS to specify a source for migration.
-     * @param aSource is a directory containing settings files to migrate from (can be empty)
+     *
+     * @param aSource is a directory containing settings files to migrate from (can be empty).
      */
     void SetMigrationSource( const wxString& aSource ) { m_migration_source = aSource; }
 
     void SetMigrateLibraryTables( bool aMigrate = true ) { m_migrateLibraryTables = aMigrate; }
 
     /**
-     * Retrieves the name of the most recent previous KiCad version that can be found in the
+     * Retrieve the name of the most recent previous KiCad version that can be found in the
-     * user settings directory.  For legacy versions (5.x, and 5.99 builds before this code was
+     * user settings directory.
-     * written), this will return "5.x"
      *
-     * @param aName is filled with the name of the previous version, if one exists
+     * For legacy versions (5.x, and 5.99 builds before this code was written), this will return
-     * @return true if a previous version to migrate from exists
+     * "5.x".
+     *
+     * @param aName is filled with the name of the previous version, if one exists.
+     * @return true if a previous version to migrate from exists.
      */
     bool GetPreviousVersionPaths( std::vector<wxString>* aName = nullptr );
 
     /**
-     * Re-scans the color themes directory, reloading any changes it finds.
+     * Re-scan the color themes directory, reloading any changes it finds.
      */
     void ReloadColorSettings();
 
     /**
-     * Loads a project or sets up a new project with a specified path
+     * Load a project or sets up a new project with a specified path.
-     * @param aFullPath is the full path to the project
+     *
-     * @param aSetActive if true will set the loaded project as the active project
+     * @param aFullPath is the full path to the project.
-     * @return true if the PROJECT_FILE was successfully loaded from disk
+     * @param aSetActive if true will set the loaded project as the active project.
+     * @return true if the #PROJECT_FILE was successfully loaded from disk.
      */
     bool LoadProject( const wxString& aFullPath, bool aSetActive = true );
 
     /**
-     * Saves, unloads and unregisters the given PROJECT
+     * Save, unload and unregister the given #PROJECT.
-     * @param aProject is the project object to unload
+     *
-     * @param aSave if true will save the project before unloading
+     * @param aProject is the project object to unload.
-     * @return true if the PROJECT file was successfully saved
+     * @param aSave if true will save the project before unloading.
+     * @return true if the #PROJECT file was successfully saved.
      */
     bool UnloadProject( PROJECT* aProject, bool aSave = true );
 
     /**
-     * Helper for checking if we have a project open
+     * Helper for checking if we have a project open.
-     * TODO: This should be deprecated along with Prj() once we support multiple projects fully
+     *
-     * @return true if a call to Prj() will succeed
+     * @todo This should be deprecated along with Prj() once we support multiple projects fully.
+     *
+     * @return true if a call to Prj() will succeed.
      */
     bool IsProjectOpen() const;
 
     /**
-     * Helper for checking if we have a project open that is not a dummy project
+     * Helper for checking if we have a project open that is not a dummy project.
-     * @return true if a call to Prj() will succeed and the project is not a dummy project
+     *
+     * @return true if a call to Prj() will succeed and the project is not a dummy project.
      */
     bool IsProjectOpenNotDummy() const;
 
     /**
-     * A helper while we are not MDI-capable -- return the one and only project
+     * A helper while we are not MDI-capable -- return the one and only project.
-     * @return the loaded project
+     *
+     * @return the loaded project.
      */
     PROJECT& Prj() const;
 
     /**
-     * Retrieves a loaded project by name
+     * Retrieve a loaded project by name.
-     * @param aFullPath is the full path including name and extension to the project file
+     *
-     * @return a pointer to the project if loaded, or nullptr
+     * @param aFullPath is the full path including name and extension to the project file.
+     * @return a pointer to the project if loaded, or nullptr.
      */
     PROJECT* GetProject( const wxString& aFullPath ) const;
 
     /**
-     * @return a list of open projects
+     * @return a list of open projects.
      */
     std::vector<wxString> GetOpenProjects() const;
 
     /**
-     * Saves a loaded project.
+     * Save a loaded project.
+     *
      * @param aFullPath is the project name to save.  If empty, will save the first loaded project.
-     * @param aProject is the project to save, or nullptr to save the active project (Prj() return)
+     * @param aProject is the project to save, or nullptr to save the active project (Prj() return).
-     * @return true if save was successful
+     * @return true if save was successful.
      */
     bool SaveProject( const wxString& aFullPath = wxEmptyString, PROJECT* aProject = nullptr );
 
     /**
-     * Sets the currently loaded project path and saves it (pointers remain valid)
+     * Set the currently loaded project path and saves it (pointers remain valid).
-     * Note that this will not modify the read-only state of the project, so it will have no effect
+     *
+     * @note that this will not modify the read-only state of the project, so it will have no effect
      * if the project is marked as read-only!
-     * @param aFullPath is the full filename to set for the project
+     *
-     * @param aProject is the project to save, or nullptr to save the active project (Prj() return)
+     * @param aFullPath is the full filename to set for the project.
+     * @param aProject is the project to save, or nullptr to save the active project (Prj() return).
      */
     void SaveProjectAs( const wxString& aFullPath, PROJECT* aProject = nullptr );
 
     /**
-     * Saves a copy of the current project under the given path.  Will save the copy even if the
+     * Save a copy of the current project under the given path.
-     * current project is marked as read-only.
+     *
-     * @param aFullPath is the full filename to set for the project
+     * @warning This will save the copy even if the current project is marked as read-only.
-     * @param aProject is the project to save, or nullptr to save the active project (Prj() return)
+     *
+     * @param aFullPath is the full filename to set for the project.
+     * @param aProject is the project to save, or nullptr to save the active project (Prj() return).
      */
     void SaveProjectCopy( const wxString& aFullPath, PROJECT* aProject = nullptr );
 
     /**
-     * @return the full path to where project backups should be stored
+     * @return the full path to where project backups should be stored.
      */
     wxString GetProjectBackupsPath() const;
 
     /**
-     * Creates a backup archive of the current project
+     * Create a backup archive of the current project.
-     * @param aReporter is used for progress reporting
+     *
+     * @param aReporter is used for progress reporting.
      * @param aTarget is the full path to the backup file.  If empty, will generate and return the
      * full path to the backup file.
-     * @return true if everything succeeded
+     * @return true if everything succeeded.
      */
     bool BackupProject( REPORTER& aReporter, wxFileName& aTarget ) const;
 
     /**
-     * Calls BackupProject if a new backup is needed according to the current backup policy.
+     * Call BackupProject() if a new backup is needed according to the current backup policy.
-     * @param aReporter is used for progress reporting
+     *
-     * @return if everything succeeded
+     * @param aReporter is used for progress reporting.
+     * @return if everything succeeded.
      */
     bool TriggerBackupIfNeeded( REPORTER& aReporter ) const;
 
     /**
-     * Checks if a given path is probably a valid KiCad configuration directory.
+     * Check if a given path is probably a valid KiCad configuration directory.
+     *
      * Actually it just checks if a file called "kicad_common" exists, because that's probably
      * good enough for now.
      *
-     * @param aPath is the path to check
+     * @param aPath is the path to check.
-     * @return true if the path contains KiCad settings
+     * @return true if the path contains KiCad settings.
      */
     static bool IsSettingsPathValid( const wxString& aPath );
 
     /**
-     * Returns the path where color scheme files are stored; creating it if missing
+     * Return the path where color scheme files are stored; creating it if missing
-     * (normally ./colors/ under the user settings path)
+     * (normally ./colors/ under the user settings path).
      */
     static wxString GetColorSettingsPath();
 
     /**
-     * Parses the current KiCad build version and extracts the major and minor revision to use
+     * Parse the current KiCad build version and extracts the major and minor revision to use
      * as the name of the settings directory for this KiCad version.
      *
-     * @return a string such as "5.1"
+     * @return a string such as "5.1".
      */
     static std::string GetSettingsVersion();
 
     /**
-     * A proxy for PATHS::GetUserSettingsPath rather than fighting swig
+     * A proxy for PATHS::GetUserSettingsPath() rather than fighting swig.
      */
     static wxString GetUserSettingsPath();
+
 private:
     JSON_SETTINGS* registerSettings( JSON_SETTINGS* aSettings, bool aLoadNow = true );
 
     /**
-     * Compares two settings versions, like "5.99" and "6.0"
+     * Compare two settings versions, like "5.99" and "6.0".
-     * @return -1 if aFirst is older than aSecond, 1 if aFirst is newer than aSecond, 0 otherwise
+     *
+     * @return -1 if aFirst is older than aSecond, 1 if aFirst is newer than aSecond, 0 otherwise.
      */
     static int compareVersions( const std::string& aFirst, const std::string& aSecond );
 
     /**
-     * Extracts the numeric version from a given settings string
+     * Extract the numeric version from a given settings string.
-     * @param aVersionString is the string to split at the "."
+     *
-     * @param aMajor will store the first part
+     * @param aVersionString is the string to split at the ".".
-     * @param aMinor will store the second part
+     * @param aMajor will store the first part.
-     * @return true if extraction succeeded
+     * @param aMinor will store the second part.
+     * @return true if extraction succeeded.
      */
     static bool extractVersion( const std::string& aVersionString, int* aMajor = nullptr,
                                 int* aMinor = nullptr );
 
     /**
-     * Attempts to load a color theme by name (the color theme directory and .json ext are assumed)
+     * Attempt to load a color theme by name (the color theme directory and .json ext are assumed).
-     * @param aName is the filename of the color theme (without the extension or path)
+     *
-     * @return the loaded settings, or nullptr if load failed
+     * @param aName is the filename of the color theme (without the extension or path).
+     * @return the loaded settings, or nullptr if load failed.
      */
     COLOR_SETTINGS* loadColorSettingsByName( const wxString& aName );
 
@@ -389,29 +421,31 @@ private:
     void loadAllColorSettings();
 
     /**
-     * Registers a PROJECT_FILE and attempts to load it from disk
+     * Register a #PROJECT_FILE and attempt to load it from disk.
-     * @param aProject is the project object to load the file for
+     *
-     * @return true if the PROJECT_FILE was successfully loaded
+     * @param aProject is the project object to load the file for.
+     * @return true if the #PROJECT_FILE was successfully loaded.
      */
     bool loadProjectFile( PROJECT& aProject );
 
     /**
-     * Optionally saves, and then unloads and unregisters the given PROJECT_FILE
+     * Optionally save, unload and unregister the given #PROJECT_FILE.
-     * @param aProject is the project object to unload the file for
+     *
-     * @param aSave if true will save the project file before unloading
+     * @param aProject is the project object to unload the file for.
-     * @return true if the PROJECT file was successfully saved
+     * @param aSave if true will save the project file before unloading.
+     * @return true if the #PROJECT file was successfully saved.
      */
     bool unloadProjectFile( PROJECT* aProject, bool aSave );
 
-    // Helper to create built-in colors and register them
+    ///< Helper to create built-in colors and register them.
     void registerBuiltinColorSettings();
 
 private:
 
-    /// True if running outside a UI context
+    /// True if running outside a UI context.
     bool m_headless;
 
-    /// The kiway this settings manager interacts with
+    /// The kiway this settings manager interacts with.
     KIWAY* m_kiway;
 
     std::vector<std::unique_ptr<JSON_SETTINGS>> m_settings;
@@ -426,22 +460,22 @@ private:
 
     wxString m_migration_source;
 
-    /// If true, the symbol and footprint library tables will be migrated from the previous version
+    /// If true, the symbol and footprint library tables will be migrated from the previous version.
     bool m_migrateLibraryTables;
 
-    /// True if settings loaded successfully at construction
+    /// True if settings loaded successfully at construction.
     bool m_ok;
 
-    /// Loaded projects (ownership here)
+    /// Loaded projects (ownership here).
     std::vector<std::unique_ptr<PROJECT>> m_projects_list;
 
-    /// Loaded projects, mapped according to project full name
+    /// Loaded projects, mapped according to project full name.
     std::map<wxString, PROJECT*> m_projects;
 
-    /// Loaded project files, mapped according to project full name
+    /// Loaded project files, mapped according to project full name.
     std::map<wxString, PROJECT_FILE*> m_project_files;
 
-    /// Lock for loaded project (expand to multiple once we support MDI)
+    /// Lock for loaded project (expand to multiple once we support MDI).
     std::unique_ptr<LOCKFILE> m_project_lock;
 
     static wxString backupDateTimeFormat;

include/tool/action_menu.h

@@ -43,12 +43,12 @@ class TOOL_MANAGER;
 enum class BITMAPS : unsigned int;
 
 /**
- * Defines the structure of a menu based on ACTIONs.
+ * Define the structure of a menu based on ACTIONs.
  */
 class ACTION_MENU : public wxMenu
 {
 public:
-    ///< Default constructor
+    /// Default constructor
     ACTION_MENU( bool isContextMenu, TOOL_INTERACTIVE* aTool = nullptr );
 
     ~ACTION_MENU() override;
@@ -107,8 +107,8 @@ public:
      * The difference between this function and wxMenu::AppendSubMenu() is the capability to
      * handle icons.
      *
-     * @param aMenu is the submenu to be added. This should be a new instance (use Clone()) if required
+     * @param aMenu is the submenu to be added. This should be a new instance (use Clone()) if
-     * as the menu is destructed after use.
+     *        required as the menu is destructed after use.
      */
     wxMenuItem* Add( ACTION_MENU* aMenu );
 
@@ -148,7 +148,7 @@ public:
     void Clear();
 
     /**
-     * Returns true if the menu has any enabled items
+     * Return true if the menu has any enabled items.
      */
     bool HasEnabledItems() const;
 
@@ -201,10 +201,10 @@ public:
     static constexpr bool CHECK  = true;
 
 protected:
-    ///< Return an instance of this class. It has to be overridden in inheriting classes.
+    /// Return an instance of this class. It has to be overridden in inheriting classes.
     virtual ACTION_MENU* create() const;
 
-    ///< Returns an instance of TOOL_MANAGER class.
+    /// Return an instance of TOOL_MANAGER class.
     TOOL_MANAGER* getToolManager() const;
 
     /**
@@ -241,20 +241,20 @@ protected:
      */
     wxMenuItem* appendCopy( const wxMenuItem* aSource );
 
-    ///< Initialize handlers for events.
+    /// Initialize handlers for events.
     void setupEvents();
 
-    ///< Update hot key settings for TOOL_ACTIONs in this menu.
+    /// Update hot key settings for TOOL_ACTIONs in this menu.
     void updateHotKeys();
 
-    ///< Traverse the submenus tree looking for a submenu capable of handling a particular menu
+    /// Traverse the submenus tree looking for a submenu capable of handling a particular menu
-    ///< event. In case it is handled, it is returned the aToolEvent parameter.
+    /// event. In case it is handled, it is returned the aToolEvent parameter.
     void runEventHandlers( const wxMenuEvent& aMenuEvent, OPT_TOOL_EVENT& aToolEvent );
 
-    ///< Run a function on the menu and all its submenus.
+    /// Run a function on the menu and all its submenus.
     void runOnSubmenus( std::function<void(ACTION_MENU*)> aFunction );
 
-    ///< Check if any of submenus contains a TOOL_ACTION with a specific ID.
+    /// Check if any of submenus contains a TOOL_ACTION with a specific ID.
     OPT_TOOL_EVENT findToolAction( int aId );
 
     bool    m_isForcedPosition;
@@ -265,22 +265,22 @@ protected:
     bool m_titleDisplayed;
     bool m_isContextMenu;
 
-    ///< Menu title
+    /// Menu title.
     wxString m_title;
 
-    ///< Optional icon
+    /// Optional icon.
     BITMAPS m_icon;
 
-    ///< Stores the id number of selected item.
+    /// Store the id number of selected item.
     int m_selected;
 
-    ///< Creator of the menu
+    /// Creator of the menu.
     TOOL_INTERACTIVE* m_tool;
 
-    ///< Associates tool actions with menu item IDs. Non-owning.
+    /// Associates tool actions with menu item IDs. Non-owning.
     std::map<int, const TOOL_ACTION*> m_toolActions;
 
-    ///< List of submenus.
+    /// List of submenus.
     std::list<ACTION_MENU*> m_submenus;
 
     friend class TOOL_INTERACTIVE;

include/tool/construction_manager.h

@@ -37,8 +37,8 @@ class EDA_ITEM;
 
 
 /**
- * Interface wrapper for the construction geometry preview,
+ * Interface wrapper for the construction geometry preview with a callback to signal the
- * with a callback to signal the view owner that the view needs to be updated.
+ * view owner that the view needs to be updated.
  */
 class CONSTRUCTION_VIEW_HANDLER
 {
@@ -69,11 +69,13 @@ class SNAP_LINE_MANAGER
 {
 public:
     SNAP_LINE_MANAGER( CONSTRUCTION_VIEW_HANDLER& aViewHandler );
+
     /**
      * The snap point is a special point that is located at the last point the cursor
-     * snapped to. If it is set, the construction manager may add extra construction
+     * snapped to.
-     * geometry to the helper extending from the snap point origin to the cursor,
+     *
-     * which is the 'snap line'.
+     * If it is set, the construction manager may add extra construction geometry to the helper
+     * extending from the snap point origin to the cursor, which is the 'snap line'.
      */
     void SetSnapLineOrigin( const VECTOR2I& aOrigin );
 
@@ -101,19 +103,19 @@ public:
     void SetSnappedAnchor( const VECTOR2I& aAnchorPos );
 
     /**
-     * If the snap line is active, return the best snap point that is closest to the cursor
+     * If the snap line is active, return the best snap point that is closest to the cursor.
      *
      * If there's no active snap line, return std::nullopt.
      *
      * If there's a snap very near, use that otherwise, use the grid point.
      * With this point, snap to it on an H/V axis.
      *
-     * Then, if there's a grid point near, snap to it on an H/V axis
+     * Then, if there's a grid point near, snap to it on an H/V axis.
      *
-     * @param aCursor The cursor position
+     * @param aCursor The cursor position.
-     * @param aNearestGrid The nearest grid point to the cursor
+     * @param aNearestGrid The nearest grid point to the cursor.
-     * @param aDistToNearest The distance to the nearest non-grid snap point, if any
+     * @param aDistToNearest The distance to the nearest non-grid snap point, if any.
-     * @param snapRange The snap range
+     * @param snapRange The snap range.
      */
     OPT_VECTOR2I GetNearestSnapLinePoint( const VECTOR2I& aCursor, const VECTOR2I& aNearestGrid,
                                           std::optional<int> aDistToNearest, int snapRange ) const;
@@ -130,7 +132,8 @@ private:
 
 
 /**
- * A class that mananges "construction" objects and geometry.
+ * A class that manages "construction" objects and geometry.
+ *
  * These are things like line extensions, arc centers, etc.
  */
 class CONSTRUCTION_MANAGER
@@ -149,7 +152,8 @@ public:
      * Items to be used for the construction of "virtual" anchors, for example, when snapping to
      * a point involving an _extension_ of an existing line or arc.
      *
-     * One item can have multiple construction items (e.g. an arc can have a circle and centre point).
+     * One item can have multiple construction items (e.g. an arc can have a circle and centre
+     * point).
      */
     struct CONSTRUCTION_ITEM
     {
@@ -185,7 +189,9 @@ public:
      */
     bool InvolvesAllGivenRealItems( const std::vector<EDA_ITEM*>& aItems ) const;
 
-    // Get the list of additional geometry items that should be considered
+    /**
+     * Get the list of additional geometry items that should be considered.
+     */
     void GetConstructionItems( std::vector<CONSTRUCTION_ITEM_BATCH>& aToExtend ) const;
 
     bool HasActiveConstruction() const;
@@ -197,20 +203,20 @@ private:
 
     CONSTRUCTION_VIEW_HANDLER& m_viewHandler;
 
-    // Within one "operation", there is one set of construction items that are
+    /// Within one "operation", there is one set of construction items that are
-    // "persistent", and are always shown. Usually the original item and any
+    /// "persistent", and are always shown. Usually the original item and any
-    // extensions.
+    /// extensions.
     std::optional<CONSTRUCTION_ITEM_BATCH> m_persistentConstructionBatch;
 
-    // Temporary construction items are added and removed as needed
+    /// Temporary construction items are added and removed as needed.
     std::deque<CONSTRUCTION_ITEM_BATCH> m_temporaryConstructionBatches;
 
-    // Set of all items for which construction geometry has been added
+    /// Set of all items for which construction geometry has been added.
     std::set<EDA_ITEM*> m_involvedItems;
 
     std::unique_ptr<ACTIVATION_HELPER<std::unique_ptr<PENDING_BATCH>>> m_activationHelper;
 
-    // Protects the persistent and temporary construction batches
+    /// Protects the persistent and temporary construction batches.
     mutable std::mutex m_batchesMutex;
 };
 

include/tool/coroutine.h

@@ -94,6 +94,7 @@ private:
             CONTINUE_AFTER_ROOT // a function sent a request to invoke a function on the main
                                 // stack context
         } type; // invocation type
+
         COROUTINE*    destination;  // stores the coroutine pointer for the stub OR the coroutine
                                     // ptr for the coroutine to be resumed if a
                                     // root(main-stack)-call-was initiated.
@@ -104,6 +105,7 @@ private:
     struct CONTEXT_T
     {
         libcontext::fcontext_t ctx;    // The context itself
+
 #ifdef KICAD_SANITIZE_THREADS
         void* tsan_fiber;               // The TSAN fiber for this context
         bool  own_tsan_fiber;           // Do we own this TSAN fiber? (we only delete fibers we own)
@@ -302,8 +304,8 @@ public:
         wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::Call (from routine)" ) );
 
         doCall( &args, aArg );
-        // we will not be asked to continue
 
+        // we will not be asked to continue
         return Running();
     }
 
@@ -348,8 +350,8 @@ public:
         wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::Resume (from routine)" ) );
 
         doResume( &args );
-        // we will not be asked to continue
 
+        // we will not be asked to continue
         return Running();
     }
 
@@ -424,7 +426,7 @@ private:
     }
 
 #ifndef LIBCONTEXT_HAS_OWN_STACK
-    ///< A functor that frees the stack
+    /// A functor that frees the stack.
     struct STACK_DELETER
     {
 #ifdef _WIN32
@@ -438,10 +440,11 @@ private:
 #endif
     };
 
-    ///< The size of the mappable memory page size
+    /// The size of the mappable memory page size.
     static inline size_t SystemPageSize()
     {
         static std::optional<size_t> systemPageSize;
+
         if( !systemPageSize.has_value() )
         {
 #ifdef _WIN32
@@ -453,10 +456,11 @@ private:
             systemPageSize = static_cast<size_t>( size );
 #endif
         }
+
         return systemPageSize.value();
     }
 
-    ///< Map a page-aligned memory region into our address space.
+    /// Map a page-aligned memory region into our address space.
     static inline void* MapMemory( size_t aAllocSize )
     {
 #ifdef _WIN32
@@ -473,7 +477,7 @@ private:
         return mem;
     }
 
-    ///< Change protection of memory page(s) to act as stack guards.
+    /// Change protection of memory page(s) to act as stack guards.
     static inline void GuardMemory( void* aAddress, size_t aGuardSize )
     {
 #ifdef _WIN32
@@ -493,7 +497,7 @@ private:
         return jumpIn( args );
     }
 
-    /* real entry point of the coroutine */
+    // real entry point of the coroutine
     static void callerStub( intptr_t aData )
     {
         INVOCATION_ARGS& args = *reinterpret_cast<INVOCATION_ARGS*>( aData );
@@ -556,7 +560,7 @@ private:
     }
 
 #ifndef LIBCONTEXT_HAS_OWN_STACK
-    ///< coroutine stack
+    /// Coroutine stack.
     std::unique_ptr<char[], struct STACK_DELETER> m_stack;
 #endif
 
@@ -566,17 +570,16 @@ private:
 
     bool m_running;
 
-    ///< pointer to coroutine entry arguments. Stripped of references
+    /// Pointer to coroutine entry arguments stripped of references to avoid compiler errors.
-    ///< to avoid compiler errors.
     typename std::remove_reference<ArgType>::type* m_args;
 
-    ///< saved caller context
+    /// Saved caller context.
     CONTEXT_T m_caller;
 
-    ///< main stack information
+    /// Main stack information.
     CALL_CONTEXT* m_callContext;
 
-    ///< saved coroutine context
+    /// Saved coroutine context.
     CONTEXT_T m_callee;
 
     ReturnType m_retVal;
@@ -584,6 +587,7 @@ private:
 #ifdef KICAD_USE_VALGRIND
     uint32_t m_valgrind_stack;
 #endif
+
 #ifdef KICAD_SANITIZE_ADDRESS
     void* asan_stack;
 #endif

include/tool/edit_constraints.h

@@ -104,7 +104,7 @@ public:
             m_constrainer( aConstrainer )
     {}
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_POINT& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
@@ -127,7 +127,7 @@ public:
             m_constrainer( aConstrainer )
     {}
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_POINT& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
@@ -151,7 +151,7 @@ public:
             m_constrainer( aConstrainer )
     {}
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_POINT& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
@@ -168,7 +168,7 @@ class EC_LINE : public EDIT_CONSTRAINT<EDIT_POINT>
 public:
     EC_LINE( EDIT_POINT& aConstrained, const EDIT_POINT& aConstrainer );
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_POINT& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
@@ -194,14 +194,14 @@ public:
             m_end( aEnd )
     {}
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_POINT& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
-    ///< Point that imposes the constraint (center of the circle).
+    /// Point that imposes the constraint (center of the circle).
     const EDIT_POINT& m_center;
 
-    ///< Point that imposes the constraint (decides on the radius of the circle).
+    /// Point that imposes the constraint (decides on the radius of the circle).
     const EDIT_POINT& m_end;
 };
 
@@ -217,27 +217,27 @@ public:
 
     virtual ~EC_CONVERGING();
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_LINE& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:
-    ///< Constraint for origin side segment.
+    /// Constraint for origin side segment.
     EDIT_CONSTRAINT<EDIT_POINT>* m_originSideConstraint;
 
-    ///< Constraint for end side segment.
+    /// Constraint for end side segment.
     EDIT_CONSTRAINT<EDIT_POINT>* m_endSideConstraint;
 
-    ///< Additional constraint, applied when at least two points are collinear. It is a pointer to
+    /// Additional constraint, applied when at least two points are collinear. It is a pointer to
-    ///< m_[origin/end]SideConstraint, so it should not be freed.
+    /// m_[origin/end]SideConstraint, so it should not be freed.
     EDIT_CONSTRAINT<EDIT_POINT>* m_colinearConstraint;
 
-    ///< EDIT_POINTS instance that stores currently modified lines.
+    /// EDIT_POINTS instance that stores currently modified lines.
     EDIT_POINTS& m_editPoints;
 
-    ///< Vector that represents the initial direction of the dragged segment.
+    /// Vector that represents the initial direction of the dragged segment.
     VECTOR2I m_draggedVector;
 
-    ///< Flags to indicate when dragged and neighbouring lines are (almost) collinear.
+    /// Flags to indicate when dragged and neighbouring lines are (almost) collinear.
     bool m_originCollinear;
     bool m_endCollinear;
 };
@@ -256,7 +256,7 @@ public:
     virtual ~EC_PERPLINE()
     {}
 
-    ///< @copydoc EDIT_CONSTRAINT::Apply()
+    /// @copydoc EDIT_CONSTRAINT::Apply()
     virtual void Apply( EDIT_LINE& aHandle, const GRID_HELPER& aGrid ) override;
 
 private:

include/tool/edit_points.h

@@ -186,15 +186,15 @@ public:
         return m_position == aOther.m_position;
     }
 
-    ///< Single point size in pixels
+    /// Single point size in pixels
     static const int POINT_SIZE = 8;
 
 #ifdef __WXMAC__
-    static const int BORDER_SIZE = 3;       ///< Border size when not hovering
+    static const int BORDER_SIZE = 3;       ///< Border size when not hovering.
-    static const int HOVER_SIZE  = 6;       ///< Border size when hovering
+    static const int HOVER_SIZE  = 6;       ///< Border size when hovering.
 #else
-    static const int BORDER_SIZE = 2;       ///< Border size when not hovering
+    static const int BORDER_SIZE = 2;       ///< Border size when not hovering.
-    static const int HOVER_SIZE  = 5;       ///< Border size when hovering
+    static const int HOVER_SIZE  = 5;       ///< Border size when hovering.
 #endif
 
 private:
@@ -204,11 +204,11 @@ private:
     GRID_CONSTRAINT_TYPE m_gridConstraint;  ///< Describe the grid snapping behavior.
     SNAP_CONSTRAINT_TYPE m_snapConstraint;  ///< Describe the object snapping behavior.
 
-    ///< An optional connected item record used to mimic polyLine behavior with individual
+    /// An optional connected item record used to mimic polyLine behavior with individual
-    ///< line segments.
+    /// line segments.
     std::pair<EDA_ITEM*, int>                     m_connected;
 
-    ///< Constraint for the point, NULL if none
+    /// Constraint for the point, NULL if none.
     std::shared_ptr<EDIT_CONSTRAINT<EDIT_POINT> > m_constraint;
 };
 
@@ -234,13 +234,13 @@ public:
         SetGridConstraint( SNAP_BY_GRID );
     }
 
-    ///< @copydoc EDIT_POINT::GetPosition()
+    /// @copydoc EDIT_POINT::GetPosition()
     virtual VECTOR2I GetPosition() const override
     {
         return m_origin.GetPosition() / 2 + m_end.GetPosition() / 2;
     }
 
-    ///< @copydoc EDIT_POINT::GetPosition()
+    /// @copydoc EDIT_POINT::GetPosition()
     virtual void SetPosition( const VECTOR2I& aPosition ) override
     {
         VECTOR2I difference = aPosition - GetPosition();
@@ -249,7 +249,7 @@ public:
         m_end.SetPosition( m_end.GetPosition() + difference );
     }
 
-    ///< @copydoc EDIT_POINT::ApplyConstraint()
+    /// @copydoc EDIT_POINT::ApplyConstraint()
     virtual void ApplyConstraint( const GRID_HELPER& aGrid ) override
     {
         if( m_constraint )
@@ -335,13 +335,13 @@ public:
     }
 
 private:
-    EDIT_POINT& m_origin;           ///< Origin point for a line
+    EDIT_POINT& m_origin;           ///< Origin point for a line.
-    EDIT_POINT& m_end;              ///< End point for a line
+    EDIT_POINT& m_end;              ///< End point for a line.
 
-    bool m_hasCenterPoint = true; ///< True if the line has a (useful) center point
+    bool m_hasCenterPoint = true; ///< True if the line has a (useful) center point.
-    bool m_showLine = false;      ///< True if the line itself should be drawn
+    bool m_showLine = false;      ///< True if the line itself should be drawn.
 
-    ///< Constraint for the point, NULL if none
+    /// Constraint for the point, NULL if none.
     std::shared_ptr<EDIT_CONSTRAINT<EDIT_LINE> > m_constraint;
 };
 

include/tool/edit_table_tool_base.h

@@ -95,21 +95,28 @@ protected:
         // Add editing actions to the selection tool menu
         //
         selToolMenu.AddSeparator( 100 );
-        selToolMenu.AddItem( ACTIONS::addRowAbove,   cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::addRowAbove,
-        selToolMenu.AddItem( ACTIONS::addRowBelow,   cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
-        selToolMenu.AddItem( ACTIONS::addColBefore,  cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::addRowBelow,
-        selToolMenu.AddItem( ACTIONS::addColAfter,   cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::addColBefore,
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::addColAfter,
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
 
         selToolMenu.AddSeparator( 100 );
-        selToolMenu.AddItem( ACTIONS::deleteRows,    cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::deleteRows,
-        selToolMenu.AddItem( ACTIONS::deleteColumns, cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::deleteColumns, cellSelection && SELECTION_CONDITIONS::Idle,
+                             100 );
 
         selToolMenu.AddSeparator( 100 );
         selToolMenu.AddItem( ACTIONS::mergeCells,    cellSelection && cellBlockSelection, 100 );
         selToolMenu.AddItem( ACTIONS::unmergeCells,  cellSelection && mergedCellsSelection, 100 );
 
         selToolMenu.AddSeparator( 100 );
-        selToolMenu.AddItem( ACTIONS::editTable,     cellSelection && SELECTION_CONDITIONS::Idle, 100 );
+        selToolMenu.AddItem( ACTIONS::editTable,
+                             cellSelection && SELECTION_CONDITIONS::Idle, 100 );
 
         selToolMenu.AddSeparator( 100 );
     }

include/tool/editor_conditions.h

@@ -139,44 +139,44 @@ public:
     SELECTION_CONDITION ScriptingConsoleVisible();
 
 protected:
-    ///< Helper function used by ContentModified().
+    /// Helper function used by ContentModified().
     static bool contentModifiedFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame );
 
-    ///< Helper function used by UndoAvailable().
+    /// Helper function used by UndoAvailable().
     static bool undoFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame );
 
-    ///< Helper function used by RedoAvailable().
+    /// Helper function used by RedoAvailable().
     static bool redoFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame );
 
-    ///< Helper function used by Units().
+    /// Helper function used by Units().
     static bool unitsFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame, EDA_UNITS aUnits );
 
-    ///< Helper function used by CurrentTool().
+    /// Helper function used by CurrentTool().
     static bool toolFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame,
                           const TOOL_ACTION& aTool );
 
-    ///< Helper function used by NoActiveTool().
+    /// Helper function used by NoActiveTool().
     static bool noToolFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame );
 
-    ///< Helper function used by GridVisible().
+    /// Helper function used by GridVisible().
     static bool gridFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< Helper function used by GridOverrides().
+    /// Helper function used by GridOverrides().
     static bool gridOverridesFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< Helper function used by PolarCoordinates().
+    /// Helper function used by PolarCoordinates().
     static bool polarCoordFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< Helper function used by FullscreenCursor().
+    /// Helper function used by FullscreenCursor().
     static bool cursorFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< Helper function used by DrawBoundingBoxes().
+    /// Helper function used by DrawBoundingBoxes().
     static bool bboxesFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< Helper function used by ScriptingConsoleVisible().
+    /// Helper function used by ScriptingConsoleVisible().
     static bool consoleVisibleFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame );
 
-    ///< The frame to apply the conditions to.
+    /// The frame to apply the conditions to.
     EDA_BASE_FRAME* m_frame;
 };
 

include/tool/embed_tool.h

@@ -47,7 +47,7 @@ public:
     std::vector<wxString> GetFileList();
 protected:
 
-    ///< @copydoc TOOL_INTERACTIVE::setTransitions();
+    /// @copydoc TOOL_INTERACTIVE::setTransitions();
     void setTransitions() override;
 
 private:

include/tool/grid_helper.h

@@ -86,12 +86,12 @@ public:
     virtual GRID_HELPER_GRIDS GetSelectionGrid( const SELECTION& aSelection ) const;
 
     /**
-     * Gets the coarsest grid that applies to an item.
+     * Get the coarsest grid that applies to an item.
      */
     virtual GRID_HELPER_GRIDS GetItemGrid( const EDA_ITEM* aItem ) const { return GRID_CURRENT; }
 
     /**
-     * Return the size of the specified grid
+     * Return the size of the specified grid.
      */
     virtual VECTOR2D GetGridSize( GRID_HELPER_GRIDS aGrid ) const;
 
@@ -101,7 +101,7 @@ public:
     }
 
     /**
-     * We clear the skip point by setting it to an unreachable position, thereby preventing matching
+     * Clear the skip point by setting it to an unreachable position, thereby preventing matching.
      */
     void ClearSkipPoint()
     {
@@ -130,6 +130,7 @@ public:
         ORIGIN = 8,
         VERTICAL = 16,
         HORIZONTAL = 32,
+
         // This anchor comes from 'constructed' geometry (e.g. an intersection
         // with something else), and not from some intrinsic point of an item
         // (e.g. an endpoint)
@@ -142,13 +143,12 @@ protected:
     struct ANCHOR
     {
         /**
-         *
+         * @param aPos The position of the anchor.
-         * @param aPos The position of the anchor
          * @param aFlags The flags for the anchor - this is a bitfield of ANCHOR_FLAGS,
          *               specifying the type of anchor (which may be used to filter out
-         *               unwanted anchors per the settings)
+         *               unwanted anchors per the settings).
-         * @param aPointTypes The point types that this anchor represents in geometric terms
+         * @param aPointTypes The point types that this anchor represents in geometric terms.
-         * @param aItem The item to which the anchor belongs
+         * @param aItem The item to which the anchor belongs.
          */
         ANCHOR( const VECTOR2I& aPos, int aFlags, int aPointTypes, std::vector<EDA_ITEM*> aItems ) :
                 pos( aPos ), flags( aFlags ), pointTypes( aPointTypes ),
@@ -159,7 +159,9 @@ protected:
         VECTOR2I  pos;
         int       flags;
         int       pointTypes;
-        // Items that are associated with this anchor (can be more than one, e.g. for an intersection)
+
+        /// Items that are associated with this anchor (can be more than one, e.g. for an
+        /// intersection).
         std::vector<EDA_ITEM*> items;
 
         double Distance( const VECTOR2I& aP ) const
@@ -232,15 +234,13 @@ protected:
     KIGFX::ORIGIN_VIEWITEM  m_viewAxis;
 
 private:
-    // Construction helper - this is what actually shows construction geometry
+    /// Show construction geometry (if any) on the canvas.
-    // (if any) on the canvas.
     KIGFX::CONSTRUCTION_GEOM m_constructionGeomPreview;
 
-    // Snap manager - this is what manages the construction geometry,
+    /// Manage the construction geometry, snap lines, reference points, etc.
-    // snap lines, reference points, etc.
     SNAP_MANAGER m_snapManager;
 
-    /// @brief  VIEW_ITEM for visualising anchor points, if enabled
+    /// #VIEW_ITEM for visualising anchor points, if enabled.
     std::unique_ptr<KIGFX::ANCHOR_DEBUG> m_anchorDebug;
 };
 

include/tool/picker_tool.h

@@ -36,7 +36,7 @@ class EDA_DRAW_FRAME;
 class PICKER_TOOL_BASE
 {
 public:
-    ///< 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;
@@ -110,7 +110,7 @@ public:
     int CurrentModifiers() const { return m_modifiers; }
 
 protected:
-    ///< Reinitializes tool to its initial state.
+    /// Reinitializes tool to its initial state.
     virtual void reset();
 
     EDA_DRAW_FRAME* m_frame;
@@ -142,14 +142,14 @@ public:
     /// @copydoc TOOL_INTERACTIVE::Reset()
     void Reset( RESET_REASON aReason ) override { }
 
-    ///< Main event loop.
+    /// Main event loop.
     int Main( const TOOL_EVENT& aEvent );
 
 protected:
-    ///< Applies the requested VIEW_CONTROLS settings.
+    /// Applies the requested VIEW_CONTROLS settings.
     void setControls();
 
-    ///< @copydoc TOOL_INTERACTIVE::setTransitions();
+    /// @copydoc TOOL_INTERACTIVE::setTransitions();
     void setTransitions() override;
 };
 

include/tool/point_editor_behavior.h

@@ -37,7 +37,7 @@ class SHAPE_POLY_SET;
  * updated.
  *
  * For the moment this is implemented such that it mutates an external
- * EDIT_POINTS object, but it might be able to also own the points.
+ * #EDIT_POINTS object, but it might be able to also own the points.
  */
 class POINT_EDIT_BEHAVIOR
 {
@@ -112,8 +112,10 @@ protected:
 
 // Helper macros to check the number of points in the edit points object
 // Still a bug, but at least it won't segfault if the number of points is wrong
-#define CHECK_POINT_COUNT(aPoints, aExpected) wxCHECK( aPoints.PointsSize() == aExpected, /* void */ )
+#define CHECK_POINT_COUNT( aPoints, aExpected ) \
-#define CHECK_POINT_COUNT_GE(aPoints, aExpected) wxCHECK( aPoints.PointsSize() >= aExpected, /* void */ )
+    wxCHECK( aPoints.PointsSize() == aExpected, /* void */ )
+#define CHECK_POINT_COUNT_GE( aPoints, aExpected ) \
+    wxCHECK( aPoints.PointsSize() >= aExpected, /* void */ )
 
 
 /**
@@ -292,7 +294,7 @@ private:
 /**
  * "Standard" table-cell editing behavior.
  *
- * This works over the EDA_SHAPE basis of a SCH/PCB_TABLECELL.
+ * This works over the #EDA_SHAPE basis of a SCH/PCB_TABLECELL.
  * The cells and tables themselves aren't (yet) polymorphic, so the implmentation
  * has to provide UpdateItem() to handle the actual update.
  */

include/tool/selection_conditions.h

@@ -33,7 +33,7 @@
 
 class SELECTION;
 
-///< Functor type that checks a specific condition for selected items.
+/// Functor type that checks a specific condition for selected items.
 typedef std::function<bool (const SELECTION&)> SELECTION_CONDITION;
 
 SELECTION_CONDITION operator||( const SELECTION_CONDITION& aConditionA,
@@ -153,52 +153,52 @@ public:
     static SELECTION_CONDITION LessThan( int aNumber );
 
 private:
-    ///< Helper function used by HasType()
+    /// Helper function used by HasType().
     static bool hasTypeFunc( const SELECTION& aSelection, KICAD_T aType );
 
-    ///< Helper function used by HasTypes()
+    /// Helper function used by HasTypes().
     static bool hasTypesFunc( const SELECTION& aSelection, std::vector<KICAD_T> aTypes );
 
-    ///< Helper function used by OnlyTypes()
+    /// Helper function used by OnlyTypes().
     static bool onlyTypesFunc( const SELECTION& aSelection, std::vector<KICAD_T> aTypes );
 
-    ///< Helper function used by Count()
+    /// Helper function used by Count().
     static bool countFunc( const SELECTION& aSelection, int aNumber );
 
-    ///< Helper function used by MoreThan()
+    /// Helper function used by MoreThan().
     static bool moreThanFunc( const SELECTION& aSelection, int aNumber );
 
-    ///< Helper function used by LessThan()
+    /// Helper function used by LessThan().
     static bool lessThanFunc( const SELECTION& aSelection, int aNumber );
 
-    ///< Helper function used by operator||
+    /// Helper function used by operator ||.
     static bool orFunc( const SELECTION_CONDITION& aConditionA,
                         const SELECTION_CONDITION& aConditionB, const SELECTION& aSelection )
     {
         return aConditionA( aSelection ) || aConditionB( aSelection );
     }
 
-    ///< Helper function used by operator&&
+    /// Helper function used by operator &&.
     static bool andFunc( const SELECTION_CONDITION& aConditionA,
                          const SELECTION_CONDITION& aConditionB, const SELECTION& aSelection )
     {
         return aConditionA( aSelection ) && aConditionB( aSelection );
     }
 
-    ///< Helper function used by operator!
+    /// Helper function used by operator !.
     static bool notFunc( const SELECTION_CONDITION& aCondition, const SELECTION& aSelection )
     {
         return !aCondition( aSelection );
     }
 
-    ///< Helper function used by operator||
+    /// Helper function used by operator ||.
     static bool orBoolFunc( const SELECTION_CONDITION& aConditionA,
                             SELECTION_BOOL& aConditionB, const SELECTION& aSelection )
     {
         return aConditionA( aSelection ) || aConditionB( aSelection );
     }
 
-    ///< Helper function used by operator&&
+    /// Helper function used by operator &&.
     static bool andBoolFunc( const SELECTION_CONDITION& aConditionA,
                              SELECTION_BOOL& aConditionB, const SELECTION& aSelection )
     {

include/tool/selection_tool.h

@@ -114,7 +114,8 @@ protected:
      * @param aHighlightMode should be either SELECTED or BRIGHTENED
      * @param aGroup is the group to remove the item from.
      */
-    virtual void unhighlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) = 0;
+    virtual void unhighlight( EDA_ITEM* aItem, int aHighlightMode,
+                              SELECTION* aGroup = nullptr ) = 0;
 
     /**
      * Set the configuration of m_additive, m_subtractive, m_exclusive_or, m_skip_heuristics
@@ -128,29 +129,30 @@ protected:
     bool hasModifier();
 
     /**
-     * Determines if ctrl-click is highlight net or XOR selection.
+     * Determine if ctrl-click is highlight net or XOR selection.
      */
     virtual bool ctrlClickHighlights() { return false; }
 
     bool doSelectionMenu( COLLECTOR* aCollector );
 
 protected:
-    bool            m_additive;          // Items should be added to sel (instead of replacing)
+    bool            m_additive;          ///< Items should be added to sel (instead of replacing).
-    bool            m_subtractive;       // Items should be removed from sel
+    bool            m_subtractive;       ///< Items should be removed from selection.
-    bool            m_exclusive_or;      // Items' selection state should be toggled
+    bool            m_exclusive_or;      ///< Items' selection state should be toggled.
-    bool            m_multiple;          // Multiple selection mode is active
+    bool            m_multiple;          ///< Multiple selection mode is active.
-    bool            m_skip_heuristics;   // Show disambuguation menu for all items under the
-                                         // cursor rather than trying to narrow them down first
-                                         // using heuristics
-    bool            m_highlight_modifier;// select highlight net on left click
-    bool            m_drag_additive;     // Add multiple items to selection
-    bool            m_drag_subtractive;  // Remove multiple from selection
 
-    bool            m_canceledMenu;      // Sets to true if the disambiguation menu was cancelled
+    /// Show disambiguation menu for all items under the cursor rather than trying to narrow
+    /// them down first using heuristics.
+    bool            m_skip_heuristics;
+    bool            m_highlight_modifier;///< Select highlight net on left click.
+    bool            m_drag_additive;     ///< Add multiple items to selection.
+    bool            m_drag_subtractive;  ///< Remove multiple from selection.
 
-    wxTimer         m_disambiguateTimer; // Timer to show the disambiguate menu
+    bool            m_canceledMenu;      ///< Sets to true if the disambiguation menu was canceled.
 
-    VECTOR2I        m_originalCursor;    // Location of original cursor when starting click
+    wxTimer         m_disambiguateTimer; ///< Timer to show the disambiguate menu.
+
+    VECTOR2I        m_originalCursor;    ///< Location of original cursor when starting click.
 };
 
 #endif /* INCLUDE_TOOL_SELECTION_TOOL_H_ */

include/tool/tool_action.h

@@ -273,7 +273,7 @@ public:
                  int aDefaultHotKey = 0, const std::string& aLegacyHotKeyName = "",
                  const wxString& aMenuText = wxEmptyString,
                  const wxString& aTooltip = wxEmptyString,
-                 BITMAPS aIcon = static_cast<BITMAPS>( 0 ), TOOL_ACTION_FLAGS aFlags = AF_NONE);
+                 BITMAPS aIcon = static_cast<BITMAPS>( 0 ), TOOL_ACTION_FLAGS aFlags = AF_NONE );
 
     ~TOOL_ACTION();
 
@@ -328,7 +328,7 @@ public:
      */
     bool HasCustomUIId() const { return m_uiid.has_value(); }
 
-    /*
+    /**
      * Get the unique ID for this action in the user interface system.
      *
      * This can be either set to a specific ID during creation or computed
@@ -338,7 +338,7 @@ public:
      */
     int GetUIId() const { return m_uiid.value_or( m_id + ACTION_BASE_UI_ID ); }
 
-    /*
+    /**
      * Get the base value used to offset the user interface IDs for the actions.
      */
     static int GetBaseUIId() { return ACTION_BASE_UI_ID; }
@@ -371,7 +371,8 @@ public:
     template<typename T>
     T GetParam() const
     {
-        wxASSERT_MSG( m_param.has_value(), "Attempted to get a parameter from an action with no parameter." );
+        wxASSERT_MSG( m_param.has_value(),
+                      "Attempted to get a parameter from an action with no parameter." );
 
         T param;
 
@@ -382,7 +383,8 @@ public:
         catch( const ki::bad_any_cast& e )
         {
             wxASSERT_MSG( false,
-                          wxString::Format( "Requested parameter type %s from action with parameter type %s.",
+                          wxString::Format( "Requested parameter type %s from action with "
+                                            "parameter type %s.",
                                             typeid(T).name(), m_param.type().name() ) );
         }
 
@@ -429,33 +431,35 @@ protected:
 
     friend class ACTION_MANAGER;
 
-    ///< Base ID to use inside the user interface system to offset the action IDs.
+    /// Base ID to use inside the user interface system to offset the action IDs.
     static constexpr int ACTION_BASE_UI_ID = 20000;
 
-    ///< Name of the action (convention is "app.tool.actionName")
+    /// Name of the action (convention is "app.tool.actionName")
     std::string          m_name;
     TOOL_ACTION_SCOPE    m_scope;
 
-    std::optional<TOOL_ACTION_GROUP>    m_group;    // Optional group for the action to belong to
+    std::optional<TOOL_ACTION_GROUP> m_group; ///< Optional group for the action to belong to.
 
-    const int            m_defaultHotKey;    // Default hot key
+    const int         m_defaultHotKey;    ///< Default hot key.
-    const int            m_defaultHotKeyAlt; // Default hot key alternate
+    const int         m_defaultHotKeyAlt; ///< Default hot key alternate.
-    int                  m_hotKey;         // The current hotkey (post-user-settings-application)
+    int               m_hotKey;           ///< The current hotkey (post-user-settings-application).
-    int                  m_hotKeyAlt;      // The alternate hotkey (post-user-settings-application)
-    const std::string    m_legacyName;     // Name for reading legacy hotkey settings
 
-    wxString                m_friendlyName; // User-friendly name
+    /// The alternate hotkey (post-user-settings-application).
-    std::optional<wxString> m_menuLabel;    // Menu label
+    int               m_hotKeyAlt;
-    wxString                m_tooltip;      // User-facing tooltip help text
+    const std::string m_legacyName;       ///< Name for reading legacy hotkey settings.
-    std::optional<wxString> m_description;  // Description of the action
 
-    BITMAPS              m_icon;           // Icon for the menu entry
+    wxString                m_friendlyName; ///< User-friendly name.
+    std::optional<wxString> m_menuLabel;    ///< Menu label.
+    wxString                m_tooltip;      ///< User facing tooltip help text.
+    std::optional<wxString> m_description;  ///< Description of the action.
 
-    int                  m_id;             // Unique ID for maps. Assigned by ACTION_MANAGER.
+    BITMAPS m_icon; ///< Icon for the menu entry
-    std::optional<int>   m_uiid;           // ID to use when interacting with the UI (if empty, generate one)
 
-    TOOL_ACTION_FLAGS    m_flags;
+    int                m_id;   ///< Unique ID for maps. Assigned by #ACTION_MANAGER.
-    ki::any              m_param; // Generic parameter
+    std::optional<int> m_uiid; ///< ID to use when interacting with the UI (if empty, generate one).
+
+    TOOL_ACTION_FLAGS m_flags;
+    ki::any           m_param; ///< Generic parameter.
 };
 
 #endif

include/tool/tool_base.h

@@ -45,10 +45,10 @@ class VIEW_CONTROLS;
 
 enum TOOL_TYPE
 {
-    ///< Tool that interacts with the user
+    /// Tool that interacts with the user
     INTERACTIVE = 0x01,
 
-    ///< Tool that runs in the background without any user intervention
+    /// Tool that runs in the background without any user intervention
     BATCH       = 0x02
 };
 
@@ -73,7 +73,7 @@ public:
 
     virtual ~TOOL_BASE() {};
 
-    ///< Determine the reason of reset for a tool.
+    /// Determine the reason of reset for a tool.
     enum RESET_REASON
     {
         RUN,                ///< Tool is invoked after being inactive
@@ -213,8 +213,10 @@ private:
 protected:
     TOOL_TYPE     m_type;
     TOOL_ID       m_toolId;       ///< Unique id, assigned by a TOOL_MANAGER instance.
-    std::string   m_toolName;     ///< Names are expected to obey the format application.ToolName
+
-                                  ///<   (eg. pcbnew.InteractiveSelection).
+    /// Names are expected to obey the format application.ToolName (eg.
+    /// pcbnew.InteractiveSelection).
+    std::string   m_toolName;
     TOOL_MANAGER* m_toolMgr;
 };
 

include/tool/tool_dispatcher.h

@@ -80,13 +80,13 @@ public:
     ACTION_MENU* GetCurrentMenu() const { return m_currentMenu; }
 
 private:
-    ///< Handles mouse related events (click, motion, dragging).
+    /// Handles mouse related events (click, motion, dragging).
     bool handleMouseButton( wxEvent& aEvent, int aIndex, bool aMotion );
 
-    ///< Returns the instance of VIEW, used by the application.
+    /// Returns the instance of VIEW, used by the application.
     KIGFX::VIEW* getView();
 
-    ///< Saves the state of key modifiers (Alt, Ctrl and so on).
+    /// Saves the state of key modifiers (Alt, Ctrl and so on).
     static int decodeModifiers( const wxKeyboardState* aState )
     {
         int mods = 0;
@@ -104,29 +104,29 @@ private:
     }
 
 private:
-    ///< The time threshold for a mouse button press that distinguishes between a single mouse
+    /// The time threshold for a mouse button press that distinguishes between a single mouse
-    ///< click and a beginning of drag event (expressed in milliseconds).
+    /// click and a beginning of drag event (expressed in milliseconds).
     static const int DragTimeThreshold = 300;
 
-    ///< The distance threshold for mouse cursor that distinguishes between a single mouse click
+    /// The distance threshold for mouse cursor that distinguishes between a single mouse click
-    ///< and a beginning of drag event (expressed in screen pixels).
+    /// and a beginning of drag event (expressed in screen pixels).
-    ///< System drag preferences take precedence if available
+    /// System drag preferences take precedence if available
     static const int DragDistanceThreshold = 8;
 
-    int      m_sysDragMinX;          ///< Mininum distance before drag is activated in the X axis
+    int      m_sysDragMinX;          ///< Minimum distance before drag is activated in the X axis
     int      m_sysDragMinY;          ///< Maximum distance before drag is activated in the Y axis
 
     VECTOR2D m_lastMousePos;         ///< The last mouse cursor position (in world coordinates).
     VECTOR2D m_lastMousePosScreen;   ///< The last mouse cursor position (in screen coordinates).
 
-    ///< State of mouse buttons.
+    /// State of mouse buttons.
     struct BUTTON_STATE;
     std::vector<BUTTON_STATE*> m_buttons;
 
-    ///< Instance of tool manager that cooperates with the dispatcher.
+    /// Instance of tool manager that cooperates with the dispatcher.
     TOOL_MANAGER* m_toolMgr;
 
-    ///< The menu from the main menubar currently shown (if any; nullptr otherwise)
+    /// The menu from the main menubar currently shown (if any; nullptr otherwise)
     ACTION_MENU*  m_currentMenu;
 };
 

include/tool/tool_event.h

@@ -85,42 +85,42 @@ enum TOOL_ACTIONS
 
     TA_CHANGE_LAYER         = 0x1000,
 
-    // Tool cancel event. Issued automagically when the user hits escape or selects End Tool from
+    /// Tool cancel event. Issued automagically when the user hits escape or selects End Tool from
-    // the context menu.
+    /// the context menu.
     TA_CANCEL_TOOL          = 0x2000,
 
-    // Context menu update. Issued whenever context menu is open and the user hovers the mouse
+    /// Context menu update. Issued whenever context menu is open and the user hovers the mouse
-    // over one of choices. Used in dynamic highlighting in disambiguation menu
+    /// over one of choices. Used in dynamic highlighting in disambiguation menu.
     TA_CHOICE_MENU_UPDATE   = 0x4000,
 
-    // Context menu choice. Sent if the user picked something from the context menu or
+    /// Context menu choice. Sent if the user picked something from the context menu or
-    // closed it without selecting anything.
+    /// closed it without selecting anything.
     TA_CHOICE_MENU_CHOICE   = 0x8000,
 
-    // Context menu is closed, no matter whether anything has been chosen or not.
+    /// Context menu is closed, no matter whether anything has been chosen or not.
     TA_CHOICE_MENU_CLOSED   = 0x10000,
 
     TA_CHOICE_MENU = TA_CHOICE_MENU_UPDATE | TA_CHOICE_MENU_CHOICE | TA_CHOICE_MENU_CLOSED,
 
-    // This event is sent *before* undo/redo command is performed.
+    /// This event is sent *before* undo/redo command is performed.
     TA_UNDO_REDO_PRE        = 0x20000,
 
-    // This event is sent *after* undo/redo command is performed.
+    /// This event is sent *after* undo/redo command is performed.
     TA_UNDO_REDO_POST       = 0x40000,
 
-    // Tool action (allows one to control tools).
+    /// Tool action (allows one to control tools).
     TA_ACTION               = 0x80000,
 
-    // Tool activation event.
+    /// Tool activation event.
     TA_ACTIVATE             = 0x100000,
 
-    // Tool re-activation event for tools already on the stack
+    /// Tool re-activation event for tools already on the stack.
     TA_REACTIVATE           = 0x200000,
 
-    // Model has changed (partial update).
+    /// Model has changed (partial update).
     TA_MODEL_CHANGE         = 0x400000,
 
-    // Tool priming event (a special mouse click)
+    /// Tool priming event (a special mouse click).
     TA_PRIME                = 0x800001,
 
     TA_ANY = 0xffffffff
@@ -149,9 +149,9 @@ enum TOOL_MODIFIERS
 /// Defines when a context menu is opened.
 enum CONTEXT_MENU_TRIGGER
 {
-    CMENU_BUTTON = 0,   // On the right button
+    CMENU_BUTTON = 0,   ///< On the right button.
-    CMENU_NOW,          // Right now (after TOOL_INTERACTIVE::SetContextMenu)
+    CMENU_NOW,          ///< Right now (after TOOL_INTERACTIVE::SetContextMenu).
-    CMENU_OFF           // Never
+    CMENU_OFF           ///< Never.
 };
 
 enum SYNCRONOUS_TOOL_STATE
@@ -240,61 +240,65 @@ public:
         init();
     }
 
-    ///< Returns the category (eg. mouse/keyboard/action) of an event..
+    /// Return the category (eg. mouse/keyboard/action) of an event.
     TOOL_EVENT_CATEGORY Category() const { return m_category; }
 
-    ///< Returns more specific information about the type of an event.
+    /// Returns more specific information about the type of an event.
     TOOL_ACTIONS Action() const { return m_actions; }
 
-    ///< These give a tool a method of informing the TOOL_MANAGER that a particular event should
+    /// These give a tool a method of informing the TOOL_MANAGER that a particular event should
-    ///< be passed on to subsequent tools on the stack.  Defaults to true for TC_MESSAGES; false
+    /// be passed on to subsequent tools on the stack.  Defaults to true for TC_MESSAGES; false
-    ///< for everything else.
+    /// for everything else.
     bool PassEvent() const { return m_passEvent; }
     void SetPassEvent( bool aPass = true ) { m_passEvent = aPass; }
 
-    ///< Returns if it this event has a valid position (true for mouse events and context-menu
+    /// Returns if it this event has a valid position (true for mouse events and context-menu
-    ///< or hotkey-based command events)
+    /// or hotkey-based command events).
     bool HasPosition() const { return m_hasPosition; }
     void SetHasPosition( bool aHasPosition ) { m_hasPosition = aHasPosition; }
 
-    ///< Returns if the action associated with this event should be treated as immediate regardless
+    /// Returns if the action associated with this event should be treated as immediate regardless
-    ///< of the current immediate action settings.
+    /// of the current immediate action settings.
     bool ForceImmediate() const { return m_forceImmediate; }
     void SetForceImmediate( bool aForceImmediate = true ) { m_forceImmediate = aForceImmediate; }
 
     TOOL_BASE* FirstResponder() const { return m_firstResponder; }
     void SetFirstResponder( TOOL_BASE* aTool ) { m_firstResponder = aTool; }
 
-    ///< Controls whether the tool is first being pushed to the stack or being reactivated after a pause
+    /// Control whether the tool is first being pushed to the stack or being reactivated after
+    /// a pause.
     bool IsReactivate() const { return m_reactivate; }
     void SetReactivate( bool aReactivate = true ) { m_reactivate = aReactivate; }
 
-    void SetSynchronous( std::atomic<SYNCRONOUS_TOOL_STATE>* aState ) { m_synchronousState = aState; }
+    void SetSynchronous( std::atomic<SYNCRONOUS_TOOL_STATE>* aState )
+    {
+        m_synchronousState = aState;
+    }
     std::atomic<SYNCRONOUS_TOOL_STATE>* SynchronousState() const { return m_synchronousState; }
 
     void SetCommit( COMMIT* aCommit ) { m_commit = aCommit; }
     COMMIT* Commit() const { return m_commit; }
 
-    ///< Returns information about difference between current mouse cursor position and the place
+    /// Return information about difference between current mouse cursor position and the place
-    ///< where dragging has started.
+    /// where dragging has started.
     const VECTOR2D Delta() const
     {
         return returnCheckedPosition( m_mouseDelta );
     }
 
-    ///< Returns mouse cursor position in world coordinates.
+    /// Return mouse cursor position in world coordinates.
     const VECTOR2D Position() const
     {
         return returnCheckedPosition( m_mousePos );
     }
 
-    ///< Returns the point where dragging has started.
+    /// Return the point where dragging has started.
     const VECTOR2D DragOrigin() const
     {
         return returnCheckedPosition( m_mouseDragOrigin );
     }
 
-    ///< Returns information about mouse buttons state.
+    /// Return information about mouse buttons state.
     int Buttons() const
     {
         assert( m_category == TC_MOUSE );    // this should be used only with mouse events
@@ -355,7 +359,7 @@ public:
         return m_actions == TA_PRIME;
     }
 
-    ///< Returns information about key modifiers state (Ctrl, Alt, etc.)
+    /// Return information about key modifiers state (Ctrl, Alt, etc.).
     int Modifier( int aMask = MD_MODIFIER_MASK ) const
     {
         return m_modifiers & aMask;
@@ -587,29 +591,28 @@ private:
     bool m_forceImmediate;
 
 
-    ///< Optional group that the parent action for the event belongs to
+    /// Optional group that the parent action for the event belongs to.
     std::optional<TOOL_ACTION_GROUP> m_actionGroup;
 
-    ///< True when the tool is being re-activated from the stack
+    /// True when the tool is being re-activated from the stack.
     bool m_reactivate;
 
-    ///< Difference between mouse cursor position and
+    /// Difference between mouse cursor position and the point where dragging event has started.
-    ///< the point where dragging event has started
     VECTOR2D m_mouseDelta;
 
-    ///< Current mouse cursor position
+    /// Current mouse cursor position.
     VECTOR2D m_mousePos;
 
-    ///< Point where dragging has started
+    /// Point where dragging has started.
     VECTOR2D m_mouseDragOrigin;
 
-    ///< State of mouse buttons
+    /// State of mouse buttons.
     int m_mouseButtons;
 
-    ///< Stores code of pressed/released key
+    /// Stores code of pressed/released key.
     int m_keyCode;
 
-    ///< State of key modifiers (Ctrl/Alt/etc.)
+    /// State of key modifiers (Ctrl/Alt/etc.).
     int m_modifiers;
 
     std::atomic<SYNCRONOUS_TOOL_STATE>* m_synchronousState;
@@ -617,10 +620,10 @@ private:
     /// Commit the tool handling the event should add to
     COMMIT* m_commit;
 
-    ///< Generic parameter used for passing non-standard data.
+    /// Generic parameter used for passing non-standard data.
     ki::any m_param;
 
-    ///< The first tool to receive the event
+    /// The first tool to receive the event.
     TOOL_BASE* m_firstResponder;
 
     std::optional<int> m_commandId;
@@ -640,17 +643,17 @@ public:
     typedef std::deque<TOOL_EVENT>::iterator iterator;
     typedef std::deque<TOOL_EVENT>::const_iterator const_iterator;
 
-    ///< Default constructor. Creates an empty list.
+    /// Default constructor. Creates an empty list.
     TOOL_EVENT_LIST()
     {}
 
-    ///< Constructor for a list containing only one TOOL_EVENT.
+    /// Constructor for a list containing only one TOOL_EVENT.
     TOOL_EVENT_LIST( const TOOL_EVENT& aSingleEvent )
     {
         m_events.push_back( aSingleEvent );
     }
 
-    ///< Copy an existing TOOL_EVENT_LIST
+    /// Copy an existing TOOL_EVENT_LIST
     TOOL_EVENT_LIST( const TOOL_EVENT_LIST& aEventList )
     {
         m_events.clear();
@@ -660,15 +663,14 @@ public:
     }
 
     /**
-     * Function Format()
+     * Return information about event in form of a human-readable string.
-     * Returns information about event in form of a human-readable string.
      *
      * @return Event information.
      */
     const std::string Format() const;
 
     /**
-     * Returns a string containing the names of all the events in this list.
+     * Return a string containing the names of all the events in this list.
      *
      * @return Event names.
      */

include/tool/tool_manager.h

@@ -75,7 +75,7 @@ public:
     typedef std::list<TOOL_ID> ID_LIST;
 
     /**
-     * Generates a unique ID from for a tool with given name.
+     * Generate a unique ID from for a tool with given name.
      */
     static TOOL_ID MakeToolId( const std::string& aToolName );
 
@@ -138,8 +138,8 @@ public:
      *
      * The common format for action names is "application.ToolName.Action".
      *
-     * Note: The type of the optional parameter must match exactly with the type the consuming
+     * @note The type of the optional parameter must match exactly with the type the consuming
-     *       action is expecting, otherwise an assert will occur when reading the paramter.
+     *       action is expecting, otherwise an assert will occur when reading the parameter.
      *
      * @param aActionName is the name of action to be invoked.
      * @param aParam is an optional parameter that might be used by the invoked action. Its meaning
@@ -166,13 +166,13 @@ public:
     /**
      * Run the specified action immediately, pausing the current action to run the new one.
      *
-     * Note: The type of the optional parameter must match exactly with the type the consuming
+     * @note The type of the optional parameter must match exactly with the type the consuming
-     *       action is expecting, otherwise an assert will occur when reading the paramter.
+     *       action is expecting, otherwise an assert will occur when reading the parameter.
      *
      * @param aAction is the action to be invoked.
      * @param aParam is an optional parameter that might be used by the invoked action. Its meaning
      *               depends on the action.
-     * @return True if the action was handled immediately
+     * @return True if the action was handled immediately.
      */
     template<typename T, std::enable_if_t<!std::is_convertible_v<T, COMMIT*>>* = nullptr>
     bool RunAction( const TOOL_ACTION& aAction, T aParam )
@@ -186,8 +186,8 @@ public:
     /**
      * Run the specified action immediately, pausing the current action to run the new one.
      *
-     * Note: The type of the optional parameter must match exactly with the type the consuming
+     * @note The type of the optional parameter must match exactly with the type the consuming
-     *       action is expecting, otherwise an assert will occur when reading the paramter.
+     *       action is expecting, otherwise an assert will occur when reading the parameter.
      *
      * @param aAction is the action to be invoked.
      * @param aCommit is the commit object the tool handling the action should add the new edits to
@@ -223,8 +223,8 @@ public:
      *
      * The common format for action names is "application.ToolName.Action".
      *
-     * Note: The type of the optional parameter must match exactly with the type the consuming
+     * @note The type of the optional parameter must match exactly with the type the consuming
-     *       action is expecting, otherwise an assert will occur when reading the paramter.
+     *       action is expecting, otherwise an assert will occur when reading the parameter.
      *
      * @param aActionName is the name of action to be invoked.
      * @param aParam is an optional parameter that might be used by the invoked action. Its meaning
@@ -251,8 +251,8 @@ public:
     /**
      * Run the specified action after the current action (coroutine) ends.
      *
-     * Note: The type of the optional parameter must match exactly with the type the consuming
+     * @nite The type of the optional parameter must match exactly with the type the consuming
-     *       action is expecting, otherwise an assert will occur when reading the paramter.
+     *       action is expecting, otherwise an assert will occur when reading the parameter.
      *
      * @param aAction is the action to be invoked.
      * @param aParam is an optional parameter that might be used by the invoked action. Its meaning
@@ -296,7 +296,7 @@ public:
      */
     void PrimeTool( const VECTOR2D& aPosition );
 
-    ///< @copydoc ACTION_MANAGER::GetHotKey()
+    /// @copydoc ACTION_MANAGER::GetHotKey()
     int GetHotKey( const TOOL_ACTION& aAction ) const;
 
     ACTION_MANAGER* GetActionManager() const { return m_actionMgr; }
@@ -354,7 +354,7 @@ public:
     void ResetTools( TOOL_BASE::RESET_REASON aReason );
 
     /**
-     * Initializes all registered tools.
+     * Initialize all registered tools.
      *
      * If a tool fails during the initialization, it is deactivated and becomes unavailable
      * for further use. Initialization should be done only once.
@@ -630,28 +630,28 @@ private:
     void setActiveState( TOOL_STATE* aState );
 
 private:
-    ///< List of tools in the order they were registered
+    /// List of tools in the order they were registered.
     std::vector<TOOL_BASE*> m_toolOrder;
 
-    ///< Index of registered tools current states, associated by tools' objects.
+    /// Index of registered tools current states, associated by tools' objects.
     TOOL_STATE_MAP m_toolState;
 
-    ///< Index of the registered tools current states, associated by tools' names.
+    /// Index of the registered tools current states, associated by tools' names.
     NAME_STATE_MAP m_toolNameIndex;
 
-    ///< Index of the registered tools current states, associated by tools' ID numbers.
+    /// Index of the registered tools current states, associated by tools' ID numbers.
     ID_STATE_MAP m_toolIdIndex;
 
-    ///< Index of the registered tools to easily lookup by their type.
+    /// Index of the registered tools to easily lookup by their type.
     std::map<const char*, TOOL_BASE*> m_toolTypes;
 
-    ///< Stack of the active tools
+    /// Stack of the active tools.
     ID_LIST m_activeTools;
 
-    ///< Instance of ACTION_MANAGER that handles TOOL_ACTIONs
+    /// Instance of ACTION_MANAGER that handles TOOL_ACTIONs.
     ACTION_MANAGER* m_actionMgr;
 
-    ///< Original cursor position, if overridden by the context menu handler
+    /// Original cursor position, if overridden by the context menu handler.
     std::map<TOOL_ID, std::optional<VECTOR2D>> m_cursorSettings;
 
     EDA_ITEM*             m_model;
@@ -660,24 +660,24 @@ private:
     TOOLS_HOLDER*         m_frame;
     APP_SETTINGS_BASE*    m_settings;
 
-    ///< Queue that stores events to be processed at the end of the event processing cycle.
+    /// Queue that stores events to be processed at the end of the event processing cycle.
     std::list<TOOL_EVENT> m_eventQueue;
 
-    ///< Right click context menu position.
+    /// Right click context menu position.
     VECTOR2D m_menuCursor;
 
     bool m_warpMouseAfterContextMenu;
 
-    ///< Flag indicating whether a context menu is currently displayed.
+    /// Flag indicating whether a context menu is currently displayed.
     bool m_menuActive;
 
-    ///< Tool currently displaying a popup menu. It is negative when there is no menu displayed.
+    /// Tool currently displaying a popup menu. It is negative when there is no menu displayed.
     TOOL_ID m_menuOwner;
 
-    ///< Pointer to the state object corresponding to the currently executed tool.
+    /// Pointer to the state object corresponding to the currently executed tool.
     TOOL_STATE* m_activeState;
 
-    ///< True if the tool manager is shutting down (don't process additional events)
+    /// True if the tool manager is shutting down (don't process additional events)
     bool m_shuttingDown;
 };
 

include/view/view.h

@@ -737,10 +737,10 @@ public:
      */
     std::unique_ptr<VIEW> DataReference() const;
 
-    ///< Maximum number of layers that may be shown
+    /// Maximum number of layers that may be shown.
     static constexpr int VIEW_MAX_LAYERS = MAX_LAYERS_FOR_VIEW;
 
-    ///< Rendering order modifier for layers that are marked as top layers.
+    /// Rendering order modifier for layers that are marked as top layers.
     static constexpr int TOP_LAYER_MODIFIER = -MAX_LAYERS_FOR_VIEW;
 
 protected:
@@ -748,14 +748,19 @@ protected:
     {
         bool                    visible;         ///< Is the layer to be rendered?
         bool                    displayOnly;     ///< Is the layer display only?
-        bool                    diffLayer;       ///< Layer should be drawn differentially over lower layers
+
-        bool                    hasNegatives;    ///< Layer should be drawn separately to not delete lower layers
+        /// Layer should be drawn differentially over lower layers.
+        bool                    diffLayer;
+
+        /// Layer should be drawn separately to not delete lower layers.
+        bool                    hasNegatives;
         std::shared_ptr<VIEW_RTREE> items;       ///< R-tree indexing all items on this layer.
         int                     renderingOrder;  ///< Rendering order of this layer.
         int                     id;              ///< Layer ID.
         RENDER_TARGET           target;          ///< Where the layer should be rendered.
-        std::set<int>           requiredLayers;  ///< Layers that have to be enabled to show
+
-                                                 ///< the layer.
+        ///< Layers that have to be enabled to show the layer.
+        std::set<int>           requiredLayers;
 
         bool operator< ( const VIEW_LAYER& aOther ) const
         {
@@ -767,7 +772,7 @@ protected:
 
     VIEW( const VIEW& ) = delete;
 
-    ///* Redraws contents within rect aRect
+    /// Redraw contents within rectangle \a aRect.
     void redrawRect( const BOX2I& aRect );
 
     inline void markTargetClean( int aTarget )
@@ -807,11 +812,11 @@ protected:
      */
     void draw( VIEW_GROUP* aGroup, bool aImmediate = false );
 
-    ///< Sort m_orderedLayers when layer rendering order has changed
+    /// Sort m_orderedLayers when layer rendering order has changed.
     void sortOrderedLayers();
 
-    ///< Clear cached GAL group numbers (*ONLY* numbers stored in VIEW_ITEMs, not group objects
+    /// Clear cached GAL group numbers (*ONLY* numbers stored in VIEW_ITEMs, not group objects
-    ///< used by GAL)
+    /// used by GAL).
     void clearGroupCache();
 
     /**
@@ -822,25 +827,25 @@ protected:
      */
     void invalidateItem( VIEW_ITEM* aItem, int aUpdateFlags );
 
-    ///< Update colors that are used for an item to be drawn
+    /// Update colors that are used for an item to be drawn.
     void updateItemColor( VIEW_ITEM* aItem, int aLayer );
 
-    ///< Update all information needed to draw an item
+    /// Update all information needed to draw an item.
     void updateItemGeometry( VIEW_ITEM* aItem, int aLayer );
 
-    ///< Update bounding box of an item
+    /// Update bounding box of an item.
     void updateBbox( VIEW_ITEM* aItem );
 
-    ///< Update set of layers that an item occupies
+    /// Update set of layers that an item occupies.
     void updateLayers( VIEW_ITEM* aItem );
 
-    ///< Determine rendering order of layers. Used in display order sorting function.
+    /// Determine rendering order of layers. Used in display order sorting function.
     static bool compareRenderingOrder( VIEW_LAYER* aI, VIEW_LAYER* aJ )
     {
         return aI->renderingOrder > aJ->renderingOrder;
     }
 
-    ///< Check if every layer required by the aLayerId layer is enabled.
+    /// Check if every layer required by the aLayerId layer is enabled.
     bool areRequiredLayersEnabled( int aLayerId ) const;
 
     // Function objects that need to access VIEW/VIEW_ITEM private/protected members
@@ -853,22 +858,22 @@ protected:
     std::unique_ptr<KIGFX::VIEW_GROUP> m_preview;
     std::vector<VIEW_ITEM *>            m_ownedItems;
 
-    ///< Whether to use rendering order modifier or not.
+    /// Whether to use rendering order modifier or not.
     bool                               m_enableOrderModifier;
 
-    ///< The set of possible displayed layers and its properties.
+    /// The set of possible displayed layers and its properties.
     std::map<int, VIEW_LAYER>          m_layers;
 
-    ///< Sorted list of pointers to members of m_layers.
+    /// Sorted list of pointers to members of m_layers.
     std::vector<VIEW_LAYER*>           m_orderedLayers;
 
-    ///< Flat list of all items.
+    /// Flat list of all items.
     std::shared_ptr<std::vector<VIEW_ITEM*>> m_allItems;
 
-    ///< The set of layers that are displayed on the top.
+    /// The set of layers that are displayed on the top.
     std::set<unsigned int>             m_topLayers;
 
-    ///< Center point of the VIEW (the point at which we are looking at).
+    /// Center point of the VIEW (the point at which we are looking at).
     VECTOR2D                           m_center;
 
     double                             m_scale;
@@ -879,22 +884,22 @@ protected:
     bool                               m_mirrorX;
     bool                               m_mirrorY;
 
-    ///< PAINTER contains information how do draw items.
+    /// PAINTER contains information how do draw items.
     PAINTER* m_painter;
 
-    ///< Interface to #PAINTER that is used to draw items.
+    /// Interface to #PAINTER that is used to draw items.
     GAL* m_gal;
 
-    ///< Flag to mark targets as dirty so they have to be redrawn on the next refresh event.
+    /// Flag to mark targets as dirty so they have to be redrawn on the next refresh event.
     bool m_dirtyTargets[TARGETS_NUMBER];
 
-    ///< Flag to respect draw priority when drawing items.
+    /// Flag to respect draw priority when drawing items.
     bool m_useDrawPriority;
 
-    ///< The next sequential drawing priority.
+    /// The next sequential drawing priority.
     int m_nextDrawPriority;
 
-    ///< Flag to reverse the draw order when using draw priority.
+    /// Flag to reverse the draw order when using draw priority.
     bool m_reverseDrawOrder;
 };
 } // namespace KIGFX

include/view/view_controls.h

@@ -38,7 +38,7 @@ namespace KIGFX
 class VIEW;
 
 
-///< Structure to keep VIEW_CONTROLS settings for easy store/restore operations
+/// Structure to keep VIEW_CONTROLS settings for easy store/restore operations.
 struct GAL_API VC_SETTINGS
 {
     VC_SETTINGS()
@@ -46,87 +46,87 @@ struct GAL_API VC_SETTINGS
         Reset();
     }
 
-    ///< Restore the default settings.
+    /// Restore the default settings.
     void Reset();
 
-    ///< Flag determining the cursor visibility.
+    /// Flag determining the cursor visibility.
     bool m_showCursor;
 
-    ///< Forced cursor position (world coordinates).
+    /// Forced cursor position (world coordinates).
     VECTOR2D m_forcedPosition;
 
-    ///< Is the forced cursor position enabled.
+    /// Is the forced cursor position enabled.
     bool m_forceCursorPosition;
 
-    ///< Should the cursor be locked within the parent window area.
+    /// Should the cursor be locked within the parent window area.
     bool m_cursorCaptured;
 
-    ///< Should the cursor snap to grid or move freely.
+    /// Should the cursor snap to grid or move freely.
     bool m_snappingEnabled;
 
-    ///< Flag for grabbing the mouse cursor.
+    /// Flag for grabbing the mouse cursor.
     bool m_grabMouse;
 
-    ///< Flag for automatic focus switching between Schematic and PCB editors.
+    /// Flag for automatic focus switching between Schematic and PCB editors.
     bool m_focusFollowSchPcb;
 
-    ///< Flag for turning on autopanning.
+    /// Flag for turning on autopanning.
     bool m_autoPanEnabled;
 
-    ///< Flag for turning on autopanning.
+    /// Flag for turning on autopanning.
     bool m_autoPanSettingEnabled;
 
-    ///< Distance from cursor to VIEW edge when panning is active.
+    /// Distance from cursor to VIEW edge when panning is active.
     float m_autoPanMargin;
 
-    ///< How fast is panning when in auto mode.
+    /// How fast is panning when in auto mode.
     float m_autoPanSpeed;
 
-    ///< How fast does panning accelerate when approaching the window boundary.
+    /// How fast does panning accelerate when approaching the window boundary.
     float m_autoPanAcceleration;
 
-    ///< If the cursor is allowed to be warped.
+    /// If the cursor is allowed to be warped.
     bool m_warpCursor;
 
-    ///< Enable horizontal panning with the horizontal scroll/trackpad input.
+    /// Enable horizontal panning with the horizontal scroll/trackpad input.
     bool m_horizontalPan;
 
-    ///< Enable the accelerating zoom controller.
+    /// Enable the accelerating zoom controller.
     bool m_zoomAcceleration;
 
-    ///< Zoom speed for the non-accelerating zoom controller.
+    /// Zoom speed for the non-accelerating zoom controller.
     int m_zoomSpeed;
 
-    ///< When true, ignore zoom_speed and pick a platform-specific default.
+    /// When true, ignore zoom_speed and pick a platform-specific default.
     bool m_zoomSpeedAuto;
 
-    ///< What modifier key to enable zoom with the (vertical) scroll wheel.
+    /// What modifier key to enable zoom with the (vertical) scroll wheel.
     int m_scrollModifierZoom;
 
-    ///< What modifier key to enable horizontal pan with the (vertical) scroll wheel.
+    /// What modifier key to enable horizontal pan with the (vertical) scroll wheel.
     int m_scrollModifierPanH;
 
-    ///< What modifier key to enable vertical with the (vertical) scroll wheel.
+    /// What modifier key to enable vertical with the (vertical) scroll wheel.
     int m_scrollModifierPanV;
 
     MOUSE_DRAG_ACTION m_dragLeft;
     MOUSE_DRAG_ACTION m_dragMiddle;
     MOUSE_DRAG_ACTION m_dragRight;
 
-    ///< Is last cursor motion event coming from keyboard arrow cursor motion action.
+    /// Is last cursor motion event coming from keyboard arrow cursor motion action.
     bool m_lastKeyboardCursorPositionValid;
 
-    ///< ACTIONS::CURSOR_UP, ACTIONS::CURSOR_DOWN, etc.
+    /// ACTIONS::CURSOR_UP, ACTIONS::CURSOR_DOWN, etc.
     long m_lastKeyboardCursorCommand;
 
-    ///< Position of the above event.
+    /// Position of the above event.
     VECTOR2D m_lastKeyboardCursorPosition;
 
 
-    ///< Whether to invert the scroll wheel movement for zoom
+    /// Whether to invert the scroll wheel movement for zoom.
     bool m_scrollReverseZoom;
 
-    ///< Whether to invert the scroll wheel movement for horizontal pan
+    /// Whether to invert the scroll wheel movement for horizontal pan.
     bool m_scrollReversePanH;
 };
 
@@ -370,26 +370,26 @@ public:
      */
     virtual void Reset();
 
-    ///< Return the current VIEW_CONTROLS settings.
+    /// Return the current VIEW_CONTROLS settings.
     const VC_SETTINGS& GetSettings() const
     {
         return m_settings;
     }
 
-    ///< Apply VIEW_CONTROLS settings from an object.
+    /// Apply VIEW_CONTROLS settings from an object.
     void ApplySettings( const VC_SETTINGS& aSettings );
 
-    ///< Load new settings from program common settings.
+    /// Load new settings from program common settings.
     virtual void LoadSettings() {}
 
 protected:
-    ///< Pointer to controlled VIEW.
+    /// Pointer to controlled VIEW.
     VIEW* m_view;
 
-    ///< Application warped the cursor, not the user (keyboard).
+    /// Application warped the cursor, not the user (keyboard).
     bool m_cursorWarped;
 
-    ///< Current VIEW_CONTROLS settings.
+    /// Current VIEW_CONTROLS settings.
     VC_SETTINGS m_settings;
 };
 } // namespace KIGFX

include/view/view_item.h

@@ -64,9 +64,10 @@ enum VIEW_UPDATE_FLAGS {
  */
 enum VIEW_VISIBILITY_FLAGS {
     VISIBLE        = 0x01,  ///< Item is visible (in general)
-    HIDDEN         = 0x02,  ///< Item is temporarily hidden (usually in favor of a being drawn
+
-                            ///<   from an overlay, such as a SELECTION).
+    /// Item is temporarily hidden (usually in favor of a being drawn from an overlay, such as a
-                            ///<   Overrides VISIBLE flag.
+    /// #SELECTION).  Overrides #VISIBLE flag.
+    HIDDEN         = 0x02,
     OVERLAY_HIDDEN = 0x04   ///< Item is temporarily hidden from being drawn on an overlay.
 };
 

include/view/view_rtree.h

@@ -48,8 +48,10 @@ public:
      */
     void Insert( VIEW_ITEM* aItem, const BOX2I& bbox )
     {
-        const int       mmin[2] = { std::min( bbox.GetX(), bbox.GetRight() ), std::min( bbox.GetY(), bbox.GetBottom() ) };
+        const int       mmin[2] = { std::min( bbox.GetX(), bbox.GetRight() ),
-        const int       mmax[2] = { std::max( bbox.GetX(), bbox.GetRight() ), std::max( bbox.GetY(), bbox.GetBottom() ) };
+                                    std::min( bbox.GetY(), bbox.GetBottom() ) };
+        const int       mmax[2] = { std::max( bbox.GetX(), bbox.GetRight() ),
+                                    std::max( bbox.GetY(), bbox.GetBottom() ) };
 
         VIEW_RTREE_BASE::Insert( mmin, mmax, aItem );
     }
@@ -65,8 +67,10 @@ public:
 
         if( aBbox )
         {
-            const int mmin[2] = { std::min( aBbox->GetX(), aBbox->GetRight() ), std::min( aBbox->GetY(), aBbox->GetBottom() ) };
+            const int mmin[2] = { std::min( aBbox->GetX(), aBbox->GetRight() ),
-            const int mmax[2] = { std::max( aBbox->GetX(), aBbox->GetRight() ), std::max( aBbox->GetY(), aBbox->GetBottom() ) };
+                                  std::min( aBbox->GetY(), aBbox->GetBottom() ) };
+            const int mmax[2] = { std::max( aBbox->GetX(), aBbox->GetRight() ),
+                                  std::max( aBbox->GetY(), aBbox->GetBottom() ) };
             VIEW_RTREE_BASE::Remove( mmin, mmax, aItem );
             return;
         }
@@ -85,8 +89,10 @@ public:
     template <class Visitor>
     void Query( const BOX2I& aBounds, Visitor& aVisitor ) const
     {
-        int   mmin[2] = { std::min( aBounds.GetX(), aBounds.GetRight() ), std::min( aBounds.GetY(), aBounds.GetBottom() ) };
+        int   mmin[2] = { std::min( aBounds.GetX(), aBounds.GetRight() ),
-        int   mmax[2] = { std::max( aBounds.GetX(), aBounds.GetRight() ), std::max( aBounds.GetY(), aBounds.GetBottom() ) };
+                          std::min( aBounds.GetY(), aBounds.GetBottom() ) };
+        int   mmax[2] = { std::max( aBounds.GetX(), aBounds.GetRight() ),
+                          std::max( aBounds.GetY(), aBounds.GetBottom() ) };
 
         // We frequently use the maximum bounding box to recache all items
         // or for any item that overflows the integer width limits of BBOX2I

include/view/wx_view_controls.h

@@ -78,50 +78,50 @@ public:
 
     void PinCursorInsideNonAutoscrollArea( bool aWarpMouseCursor ) override;
 
-    ///< @copydoc VIEW_CONTROLS::GetMousePosition()
+    /// @copydoc VIEW_CONTROLS::GetMousePosition()
     VECTOR2D GetMousePosition( bool aWorldCoordinates = true ) const override;
 
     using VIEW_CONTROLS::GetCursorPosition;
 
-    ///< @copydoc VIEW_CONTROLS::GetCursorPosition()
+    /// @copydoc VIEW_CONTROLS::GetCursorPosition()
     VECTOR2D GetCursorPosition( bool aSnappingEnabled ) const override;
 
-    ///< @copydoc VIEW_CONTROLS::GetRawCursorPosition()
+    /// @copydoc VIEW_CONTROLS::GetRawCursorPosition()
     VECTOR2D GetRawCursorPosition( bool aSnappingEnabled = true ) const override;
 
     void SetCursorPosition( const VECTOR2D& aPosition, bool warpView,
                             bool aTriggeredByArrows, long aArrowCommand ) override;
 
-    ///< @copydoc VIEW_CONTROLS::SetCrossHairCursorPosition()
+    /// @copydoc VIEW_CONTROLS::SetCrossHairCursorPosition()
     void SetCrossHairCursorPosition( const VECTOR2D& aPosition, bool aWarpView ) override;
 
-    ///< @copydoc VIEW_CONTROLS::CursorWarp()
+    /// @copydoc VIEW_CONTROLS::CursorWarp()
     void WarpMouseCursor( const VECTOR2D& aPosition, bool aWorldCoordinates = false,
                           bool aWarpView = false ) override;
 
-    ///< @copydoc VIEW_CONTROLS::CenterOnCursor()
+    /// @copydoc VIEW_CONTROLS::CenterOnCursor()
     void CenterOnCursor() override;
 
-    ///< Adjusts the scrollbars position to match the current viewport.
+    /// Adjusts the scrollbars position to match the current viewport.
     void UpdateScrollbars();
 
-    ///< End any mouse drag action still in progress
+    /// End any mouse drag action still in progress.
     void CancelDrag();
 
     void ForceCursorPosition( bool aEnabled,
                               const VECTOR2D& aPosition = VECTOR2D( 0, 0 ) ) override;
 
-    ///< Applies VIEW_CONTROLS settings from the program COMMON_SETTINGS
+    /// Applies VIEW_CONTROLS settings from the program #COMMON_SETTINGS.
     void LoadSettings() override;
 
-    ///< Event that forces mouse move event in the dispatcher (eg. used in autopanning, when
+    /// Event that forces mouse move event in the dispatcher (eg. used in autopanning, when
-    ///< mouse cursor does not move in screen coordinates, but does in world coordinates)
+    /// mouse cursor does not move in screen coordinates, but does in world coordinates)
     static const wxEventType EVT_REFRESH_MOUSE;
 
     std::unique_ptr<PROF_COUNTER> m_MotionEventCounter;
 
 private:
-    ///< Possible states for WX_VIEW_CONTROLS.
+    /// Possible states for WX_VIEW_CONTROLS.
     enum STATE
     {
         IDLE = 1,           ///< Nothing is happening.
@@ -131,7 +131,7 @@ private:
     };
 
     /**
-     * Sets the interaction state, simply a internal setter to make it easier to debug changes
+     * Set the interaction state, simply a internal setter to make it easier to debug changes.
      */
     void setState( STATE aNewState );
 
@@ -158,7 +158,9 @@ private:
      * It is mostly used for notifying the tools that the cursor position in the world
      * coordinates has changed, whereas the screen coordinates remained the same (e.g.
      * frame edge autopanning).
-     * @param aSetModifiers If false, don't change the modifiers (they were set using the keyboard motion)
+     *
+     * @param aSetModifiers If false, don't change the modifiers (they were set using the
+     *                      keyboard motion).
      */
     void refreshMouse( bool aSetModifiers);
 
@@ -167,48 +169,48 @@ private:
      */
     wxPoint getMouseScreenPosition() const;
 
-    ///< Current state of VIEW_CONTROLS.
+    /// Current state of VIEW_CONTROLS.
     STATE       m_state;
 
-    ///< Panel that is affected by VIEW_CONTROLS.
+    /// Panel that is affected by VIEW_CONTROLS.
     EDA_DRAW_PANEL_GAL* m_parentPanel;
 
-    ///< Store information about point where dragging has started.
+    /// Store information about point where dragging has started.
     VECTOR2D    m_dragStartPoint;
 
-    ///< Current direction of panning (only autopanning mode).
+    /// Current direction of panning (only autopanning mode).
     VECTOR2D    m_panDirection;
 
-    ///< Timer responsible for handling autopanning.
+    /// Timer responsible for handling autopanning.
     wxTimer     m_panTimer;
 
-    ///< Ratio used for scaling world coordinates to scrollbar position.
+    /// Ratio used for scaling world coordinates to scrollbar position.
     VECTOR2D    m_scrollScale;
 
-    ///< Current scrollbar position.
+    /// Current scrollbar position.
     VECTOR2I    m_scrollPos;
 
-    ///< The mouse position when a drag zoom started.
+    /// The mouse position when a drag zoom started.
     VECTOR2D      m_zoomStartPoint;
 
 #ifdef __WXGTK3__
-    ///< Last event timestamp used to de-bounce mouse wheel.
+    /// Last event timestamp used to de-bounce mouse wheel.
     long int    m_lastTimestamp;
 #endif
 
-    ///< Current cursor position (world coordinates).
+    /// Current cursor position (world coordinates).
     VECTOR2D    m_cursorPos;
 
-    ///< Flag deciding whether the cursor position should be calculated using the mouse position.
+    /// Flag deciding whether the cursor position should be calculated using the mouse position.
     bool        m_updateCursor;
 
-    ///< Flag to indicate if infinite panning works on this platform.
+    /// Flag to indicate if infinite panning works on this platform.
     bool m_infinitePanWorks;
 
-    ///< A #ZOOM_CONTROLLER that determines zoom steps. This is platform-specific.
+    /// A #ZOOM_CONTROLLER that determines zoom steps. This is platform-specific.
     std::unique_ptr<ZOOM_CONTROLLER> m_zoomController;
 
-    ///< Used to track gesture events.
+    /// Used to track gesture events.
     double   m_gestureLastZoomFactor;
     VECTOR2D m_gestureLastPos;
 };

include/view/zoom_controller.h

@@ -62,19 +62,19 @@ public:
 class GAL_API ACCELERATING_ZOOM_CONTROLLER : public ZOOM_CONTROLLER
 {
 public:
-    ///< The type of the acceleration timeout.
+    /// The type of the acceleration timeout.
     using TIMEOUT = std::chrono::milliseconds;
 
-    ///< The clock used for the timestamp (guaranteed to be monotonic).
+    /// The clock used for the timestamp (guaranteed to be monotonic).
     using CLOCK = std::chrono::steady_clock;
 
-    ///< The type of the time stamps.
+    /// The type of the time stamps.
     using TIME_PT = std::chrono::time_point<CLOCK>;
 
-    ///< The default timeout, after which a another scroll will not be accelerated.
+    /// The default timeout, after which a another scroll will not be accelerated.
     static constexpr TIMEOUT DEFAULT_TIMEOUT = std::chrono::milliseconds( 500 );
 
-    ///< The default minimum step factor for accelerating controller.
+    /// The default minimum step factor for accelerating controller.
     static constexpr double DEFAULT_ACCELERATION_SCALE = 5.0;
 
     /*
@@ -85,7 +85,7 @@ public:
     public:
         virtual ~TIMESTAMP_PROVIDER() = default;
 
-        /*
+        /**
          * @return the timestamp at the current time.
          */
         virtual TIME_PT GetTimestamp() = 0;
@@ -93,10 +93,10 @@ public:
 
     /**
      * @param aAccTimeout the timeout - if a scroll happens within this timeframe,
-     *                    the zoom will be faster
+     *                    the zoom will be faster.
      * @param aTimestampProv a provider for timestamps. If null, a default will be provided,
      *                       which is the main steady_clock (this is probably what you want
-     *                       for real usage)
+     *                       for real usage).
      */
     ACCELERATING_ZOOM_CONTROLLER( double aScale = DEFAULT_ACCELERATION_SCALE,
                                   const TIMEOUT& aAccTimeout = DEFAULT_TIMEOUT,
@@ -115,16 +115,16 @@ public:
     }
 
 private:
-    ///< The timestamp provider to use (might be provided externally).
+    /// The timestamp provider to use (might be provided externally).
     TIMESTAMP_PROVIDER* m_timestampProv;
 
-    ///< Any provider owned by this class (the default one, if used).
+    /// Any provider owned by this class (the default one, if used).
     std::unique_ptr<TIMESTAMP_PROVIDER> m_ownTimestampProv;
 
-    ///< The timestamp of the previous event.
+    /// The timestamp of the previous event.
     TIME_PT m_prevTimestamp;
 
-    ///< The timeout value.
+    /// The timeout value.
     TIMEOUT m_accTimeout;
 
     /// Previous rotation was positive.
@@ -150,20 +150,20 @@ public:
 
     double GetScaleForRotation( int aRotation ) override;
 
-    ///< A suitable (magic) scale factor for GTK3 systems.
+    /// A suitable (magic) scale factor for GTK3 systems.
     static constexpr double GTK3_SCALE = 0.002;
 
-    ///< A suitable (magic) scale factor for Mac systems.
+    /// A suitable (magic) scale factor for Mac systems.
     static constexpr double MAC_SCALE = 0.01;
 
     /// A suitable (magic) scale factor for Windows systems.
     static constexpr double MSW_SCALE = 0.005;
 
-    ///< Multiplier for manual scale ssetting.
+    /// Multiplier for manual scale ssetting.
     static constexpr double MANUAL_SCALE_FACTOR = 0.001;
 
 private:
-    ///< The scale factor set by the constructor.
+    /// The scale factor set by the constructor.
     double m_scale;
 };
 

include/widgets/bitmap_button.h

@@ -170,10 +170,10 @@ private:
     wxSize    m_unadjustedMinSize;
     bool      m_isToolbarButton;
 
-    ///< Accept mouse-up as click even if mouse-down happened outside of the control
+    /// Accept mouse-up as click even if mouse-down happened outside of the control.
     bool      m_acceptDraggedInClicks;
 
-    ///< Draws bitmap centered in the control
+    /// Draw bitmap centered in the control.
     bool      m_centerBitmap;
 };
 

include/widgets/bitmap_toggle.h

@@ -36,9 +36,9 @@ class wxStaticBitmap;
 wxDECLARE_EVENT( TOGGLE_CHANGED, wxCommandEvent );
 
 /**
- * A checkbox control except with custom bitmaps for the checked and unchecked states
+ * A checkbox control except with custom bitmaps for the checked and unchecked states.
  *
- * This is useful in space-constrained situations where native toggle button controls are too big
+ * This is useful in space-constrained situations where native toggle button controls are too big.
  */
 
 class BITMAP_TOGGLE : public wxPanel
@@ -49,14 +49,15 @@ public:
     BITMAP_TOGGLE( wxWindow* aParent, wxWindowID aId, const wxBitmapBundle& aCheckedBitmap,
                    const wxBitmapBundle& aUncheckedBitmap, bool aChecked = false );
 
-    ///< Set the checkbox state
+    /// Set the checkbox state
     void SetValue( bool aValue );
 
-    ///< Read the checkbox state
+    /// Read the checkbox state
     bool GetValue() const { return m_checked; }
 
     /**
-     * Updates the window ID of this control and its children
+     * Update the window ID of this control and its children.
+     *
      * @param aId new Window ID to set
      */
     void SetWindowID( wxWindowID aId )
@@ -72,7 +73,7 @@ private:
     wxBitmapBundle  m_unchecked_bitmap;
     wxBitmapBundle  m_checked_bitmap;
 
-    wxLongLong      m_debounce;            // Timestamp for debouncing events
+    wxLongLong      m_debounce;            ///< Timestamp for debouncing events.
 };
 
 #endif

include/widgets/color_swatch.h

@@ -58,18 +58,18 @@ class COLOR_SWATCH: public wxPanel
 public:
 
     /**
-     * Construct a COLOR_SWATCH
+     * Construct a COLOR_SWATCH.
      *
-     * @param aParent parent window
+     * @param aParent parent window.
-     * @param aColor initial swatch color
+     * @param aColor initial swatch color.
-     * @param aID id to use when sending swatch events
+     * @param aID id to use when sending swatch events.
      */
     COLOR_SWATCH( wxWindow* aParent, const KIGFX::COLOR4D& aColor, int aID,
                   const KIGFX::COLOR4D& aBackground, const KIGFX::COLOR4D& aDefault,
                   SWATCH_SIZE aSwatchType, bool aTriggerWithSingleClick = false );
 
     /**
-     * constructor for wxFormBuilder
+     * Constructor for wxFormBuilder.
      */
     COLOR_SWATCH( wxWindow *aParent, wxWindowID aId, const wxPoint &aPos = wxDefaultPosition,
                   const wxSize &aSize = wxDefaultSize, long aStyle = 0 );
@@ -95,13 +95,14 @@ public:
     void SetUserColors( CUSTOM_COLORS_LIST* aUserColors ) { m_userColors = aUserColors; }
 
     /**
-     * @return the current swatch color
+     * @return the current swatch color.
      */
     KIGFX::COLOR4D GetSwatchColor() const;
 
     /**
-     * Updates the window ID of this control and its children
+     * Update the window ID of this control and its children.
-     * @param aId new Window ID to set
+     *
+     * @param aId new Window ID to set.
      */
     void SetWindowID( wxWindowID aId )
     {
@@ -121,7 +122,7 @@ public:
 
     void SetSupportsOpacity( bool aSupportsOpacity ) { m_supportsOpacity = aSupportsOpacity; }
 
-    /// Registers a handler for when the user tries to interact with a read-only swatch
+    /// Register a handler for when the user tries to interact with a read-only swatch.
     void SetReadOnlyCallback( std::function<void()> aCallback ) { m_readOnlyCallback = aCallback; }
 
     /// Respond to a change in the OS's DarkMode setting.
@@ -142,7 +143,7 @@ private:
     wxBitmap makeBitmap();
 
     /**
-     * Pass unwanted events on to listeners of this object
+     * Pass unwanted events on to listeners of this object.
      */
     void rePostEvent( wxEvent& aEvent );
 
@@ -169,6 +170,6 @@ private:
 /**
  * Event signaling a swatch has changed color
  */
-wxDECLARE_EVENT(COLOR_SWATCH_CHANGED, wxCommandEvent);
+wxDECLARE_EVENT( COLOR_SWATCH_CHANGED, wxCommandEvent );
 
 #endif // COLOR_SWATCH__H_

include/widgets/grid_bitmap_toggle.h

@@ -26,7 +26,7 @@
 
 
 /**
- * A toggle button renderer for a wxGrid, similar to BITMAP_TOGGLE
+ * A toggle button renderer for a wxGrid, similar to #BITMAP_TOGGLE.
  */
 class GRID_BITMAP_TOGGLE_RENDERER : public wxGridCellRenderer
 {
@@ -42,7 +42,7 @@ public:
                int aRow, int aCol, bool aIsSelected ) override;
 
     wxSize GetBestSize( wxGrid& aGrid, wxGridCellAttr& aAttr, wxDC& aDc,
-                        int aRow, int aCol) override;
+                        int aRow, int aCol ) override;
 
 private:
     wxBitmapBundle m_bitmapChecked;

include/widgets/grid_button.h

@@ -37,7 +37,7 @@ public:
                int aRow, int aCol, bool aIsSelected ) override;
 
     wxSize GetBestSize( wxGrid& aGrid, wxGridCellAttr& aAttr, wxDC& aDc,
-                        int aRow, int aCol) override;
+                        int aRow, int aCol ) override;
 
 private:
     wxButton m_button;

include/widgets/grid_icon_text_helpers.h

@@ -55,7 +55,8 @@ public:
 
     void Draw( wxGrid& aGrid, wxGridCellAttr& aAttr, wxDC& aDC,
                const wxRect& aRect, int aRow, int aCol, bool isSelected ) override;
-    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row, int col ) override;
+    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row,
+                        int col ) override;
 
 private:
     std::vector<BITMAPS> m_icons;
@@ -77,7 +78,8 @@ public:
 
     void Draw( wxGrid& aGrid, wxGridCellAttr& aAttr, wxDC& aDC,
                const wxRect& aRect, int aRow, int aCol, bool isSelected ) override;
-    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row, int col ) override;
+    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row,
+                        int col ) override;
     wxGridCellRenderer* Clone() const override;
 
 private:
@@ -95,7 +97,8 @@ public:
 
     void Draw( wxGrid& aGrid, wxGridCellAttr& aAttr, wxDC& aDC,
                const wxRect& aRect, int aRow, int aCol, bool isSelected ) override;
-    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row, int col ) override;
+    wxSize GetBestSize( wxGrid & grid, wxGridCellAttr & attr, wxDC & dc, int row,
+                        int col ) override;
     wxGridCellRenderer* Clone() const override;
 
 private:

include/widgets/grid_readonly_text_helpers.h

@@ -34,17 +34,13 @@ class GRID_CELL_READONLY_TEXT_EDITOR : public wxGridCellTextEditor
 public:
     GRID_CELL_READONLY_TEXT_EDITOR() {};
 
-    void Create(wxWindow* parent, wxWindowID id, wxEvtHandler* evtHandler) override
+    void Create( wxWindow* parent, wxWindowID id, wxEvtHandler* evtHandler ) override
     {
-        DoCreate(parent, id, evtHandler);
+        DoCreate( parent, id, evtHandler );
         Text()->SetEditable( false );
     }
 
 wxDECLARE_NO_COPY_CLASS( GRID_CELL_READONLY_TEXT_EDITOR );
 };
 
-
-
-
-
 #endif  // GRID_READONLY_TEXT_HELPERS_H

include/widgets/indicator_icon.h

@@ -30,8 +30,7 @@
 class wxStaticBitmap;
 
 /**
- * representing a row indicator icon for use in
+ * Represent a row indicator icon for use in places like the layer widget.
- * places like the layer widget
  */
 class INDICATOR_ICON : public wxPanel
 {
@@ -46,8 +45,7 @@ public:
     using ICON_ID = int;
 
     /**
-     * A simple object that can provide fixed bitmaps for use as row
+     * A simple object that can provide fixed bitmaps for use as row indicators.
-     * indicators
      */
     class ICON_PROVIDER
     {
@@ -58,8 +56,7 @@ public:
         /**
          * Get a reference to the row icon in the given mode.
          *
-         * @param aIconId the id of the icon to get (depends on the
+         * @param aIconId the id of the icon to get (depends on the provider).
-         * provider).
          */
         virtual const wxBitmap& GetIndicatorIcon( ICON_ID aIconId ) const = 0;
     };
@@ -68,21 +65,20 @@ public:
      * Accessor for the default icon providers, which take
      * true and false for IDs, meaning on/off.
      *
-     * @param aAlternative false for blue arrow/blank, true for the
+     * @param aAlternative false for blue arrow/blank, true for the green diamond.
-     * green diamond
      */
     static ICON_PROVIDER& GetDefaultRowIconProvider( bool aAlternative );
 
     /**
-     * @param aParent the owning window
+     * @param aParent the owning window.
-     * @param aIconProvider the icon provider to get icons from
+     * @param aIconProvider the icon provider to get icons from.
      * @param aInitialIcon is the initial state of the icon (the meaning
-     * depends on what is the purpose of the icon)
+     * depends on what is the purpose of the icon).
      * @param aID the ID to use for the widgets - events will have
      * this ID.
      */
     INDICATOR_ICON( wxWindow* aParent, ICON_PROVIDER& aIconProvider,
-                   ICON_ID aInitialIcon, int aID );
+                    ICON_ID aInitialIcon, int aID );
 
     /**
      * Set the row indicator to the given state.
@@ -93,13 +89,14 @@ public:
 
 
     /**
-     * @return the current state of the indicator
+     * @return the current state of the indicator.
      */
     ICON_ID GetIndicatorState() const;
 
     /**
-     * Updates the window ID of this control and its children
+     * Update the window ID of this control and its children.
-     * @param aId new Window ID to set
+     *
+     * @param aId new Window ID to set.
      */
     void SetWindowID( wxWindowID aId )
     {
@@ -109,14 +106,13 @@ public:
 
 private:
 
-    ///< An class that delivers icons for the indicator (currently just
+    /// Object that delivers icons for the indicator (currently uses a default implementation).
-    ///< uses a default implementation).
     ICON_PROVIDER& m_iconProvider;
 
-    ///< Handle on the bitmap widget
+    /// Handle on the bitmap widget.
     wxStaticBitmap* m_bitmap;
 
-    ///< Is the icon currently "on"
+    /// Is the icon currently "on".
     ICON_ID m_currentId;
 };
 
@@ -128,7 +124,7 @@ class ROW_ICON_PROVIDER: public INDICATOR_ICON::ICON_PROVIDER
 {
 public:
 
-    ///< State constants to select the right icons
+    /// State constants to select the right icons
     enum STATE
     {
         OFF,    ///< Row "off" or "deselected"
@@ -140,11 +136,11 @@ public:
 
     /**
      * @param aAlt false: normal icons (blue arrow/blank), true:
-     * alternative icons (blue arrow/green diamond)
+     * alternative icons (blue arrow/green diamond).
      */
     ROW_ICON_PROVIDER( int aSizeDIP, wxWindow* aWindow );
 
-    ///< @copydoc INDICATOR_ICON::ICON_PROVIDER::GetIndicatorIcon()
+    /// @copydoc INDICATOR_ICON::ICON_PROVIDER::GetIndicatorIcon()
     const wxBitmap& GetIndicatorIcon( INDICATOR_ICON::ICON_ID aIconId ) const override;
 
 private:

include/widgets/kistatusbar.h

@@ -50,39 +50,41 @@ public:
 
     /**
      * Set the text in a field using wxELLIPSIZE_MIDDLE option to adjust the text size
-     * to the field size (unfortunately, setting the wxStatusBar style to wxELLIPSIZE_MIDDLE
+     * to the field size.
-     * does not work fine
+     *
+     * @note Unfortunately, setting the wxStatusBar style to wxELLIPSIZE_MIDDLE does not work.
      */
     void SetEllipsedTextField( const wxString& aText, int aFieldId );
 
     /**
-     * Shows the background progress bar
+     * Show the background progress bar.
      */
     void ShowBackgroundProgressBar( bool aCancellable = false );
 
     /**
-     * Hides the background progress bar
+     * Hide the background progress bar.
      */
     void HideBackgroundProgressBar();
 
     /**
-     * Sets the current progress of the progress bar
+     * Set the current progress of the progress bar.
      */
     void SetBackgroundProgress( int aAmount );
 
     /**
-     * Sets the maX progress of the progress bar
+     * Set the max progress of the progress bar.
      */
     void SetBackgroundProgressMax( int aAmount );
 
     /**
-     * Sets the status text that displays next to the progress bar
+     * Set the status text that displays next to the progress bar.
      */
     void SetBackgroundStatusText( const wxString& aTxt );
 
     /**
-     * Sets the notification count on the notifications button
+     * Set the notification count on the notifications button.
-     * A value of 0 will hide the count
+     *
+     * A value of 0 will hide the count.
      */
     void SetNotificationCount( int aCount );
 

include/widgets/layer_box_selector.h

@@ -41,14 +41,14 @@ public:
     bool SetLayersHotkeys( bool value );
 
 protected:
-    // Return true if the layer id is enabled (i.e. is it should be displayed)
+    /// Return true if the layer id is enabled (i.e. is it should be displayed).
     virtual bool isLayerEnabled( int aLayer ) const = 0;
 
     bool m_layerhotkeys;
 };
 
 
-/*
+/**
  * Display a layer list in a wxBitmapComboBox.
  */
 class LAYER_BOX_SELECTOR : public wxBitmapComboBox, public LAYER_SELECTOR

include/widgets/lib_tree.h

@@ -62,12 +62,12 @@ public:
     /**
      * Construct a symbol tree.
      *
-     * @param aParent parent window containing this tree widget
+     * @param aParent parent window containing this tree widget.
      * @param aRecentSearchesKey a key into a global map storing recent searches (usually "power",
-     *                           "symbols", or "footprints", but could be further differentiated)
+     *                           "symbols", or "footprints", but could be further differentiated).
-     * @param aLibTable table containing libraries and items to display
+     * @param aLibTable table containing libraries and items to display.
-     * @param aAdapter a LIB_TREE_MODEL_ADAPTER instance to use
+     * @param aAdapter a LIB_TREE_MODEL_ADAPTER instance to use.
-     * @param aFlags selection of sub-widgets to include and other options
+     * @param aFlags selection of sub-widgets to include and other options.
      * @param aDetails if not null, a custom HTML_WINDOW to hold symbol details. If null this
      *                 will be created inside the LIB_TREE.
      */
@@ -94,11 +94,12 @@ public:
     }
 
     /**
-     * Retrieves a list of selections for trees that allow multi-selection
+     * Retrieve a list of selections for trees that allow multi-selection.
+     *
      * @see GetSelectedLibId for details on how aUnit will be filled.
-     * @param aSelection will be filled with a list of selected LIB_IDs
+     * @param aSelection will be filled with a list of selected LIB_IDs.
-     * @param aUnit is an optional pointer to a list to fill with unit numbers
+     * @param aUnit is an optional pointer to a list to fill with unit numbers.
-     * @return the number of selected items
+     * @return the number of selected items.
      */
     int GetSelectedLibIds( std::vector<LIB_ID>& aSelection,
                            std::vector<int>* aUnit = nullptr ) const;
@@ -116,7 +117,7 @@ public:
     void CenterLibId( const LIB_ID& aLibId );
 
     /**
-     * Unselect currently selected item in wxDataViewCtrl
+     * Unselect currently selected item in wxDataViewCtrl.
      */
     void Unselect();
 
@@ -146,7 +147,7 @@ public:
     void Regenerate( bool aKeepState );
 
     /**
-     * Refreshes the tree (mainly to update highlighting and asterisking)
+     * Refresh the tree (mainly to update highlighting and asterisking)
      */
     void RefreshLibTree();
 
@@ -155,7 +156,7 @@ public:
     wxSizer* GetFiltersSizer() { return m_filtersSizer; }
 
     /**
-     * Focus the search widget if it exists
+     * Focus the search widget if it exists.
      */
     void FocusSearchFieldIfExists();
 
@@ -183,7 +184,7 @@ protected:
     void postPreselectEvent();
 
     /**
-     * Post SYMBOL_SELECTED event to notify the selection handler that a part has been selected.
+     * Post #SYMBOL_SELECTED event to notify the selection handler that a part has been selected.
      */
     void postSelectEvent();
 
@@ -192,10 +193,10 @@ protected:
      */
     struct STATE
     {
-        ///< List of expanded nodes
+        /// List of expanded nodes.
         std::vector<wxDataViewItem> expanded;
 
-        ///< Current selection, might be not valid if nothing was selected
+        /// Current selection, might be not valid if nothing was selected.
         LIB_ID selection;
     };
 
@@ -259,10 +260,10 @@ protected:
     bool               m_previewDisabled;
 };
 
-///< Custom event sent when an item is selected in the list
+/// Custom event sent when an item is selected in the list.
 wxDECLARE_EVENT( EVT_LIBITEM_SELECTED, wxCommandEvent );
 
-///< Custom event sent when an item is chosen (double-clicked)
+/// Custom event sent when an item is chosen (double-clicked).
 wxDECLARE_EVENT( EVT_LIBITEM_CHOSEN, wxCommandEvent );
 
 #endif /* LIB_TREE_H */

include/widgets/listbox_tricks.h

@@ -80,6 +80,7 @@ private:
     void listBoxPaste();
 
     wxArrayString listBoxGetSelected() const;
+
     /**
      * Delete the selected filters.
      *

include/widgets/msgpanel.h

@@ -102,7 +102,7 @@ class EDA_MSG_PANEL : public wxPanel
 public:
     EDA_MSG_PANEL( wxWindow* aParent, int aId,
                    const wxPoint& aPosition, const wxSize& aSize,
-                   long style=wxTAB_TRAVERSAL, const wxString& name=wxPanelNameStr);
+                   long style=wxTAB_TRAVERSAL, const wxString& name=wxPanelNameStr );
     ~EDA_MSG_PANEL();
 
     void OnPaint( wxPaintEvent& aEvent );

include/widgets/text_ctrl_eval.h

@@ -31,7 +31,8 @@
 #include <libeval/numeric_evaluator.h>
 
 /**
- * @brief wxTextCtrl wrapper to handle math expression evaluation.
+ * wxTextCtrl wrapper to handle math expression evaluation.
+ *
  * Expressions are evaluated after the text control loses the focus. If user decides to modify
  * the expression, he will get the original expression to modify.
  */
@@ -49,7 +50,7 @@ public:
     }
 
     /**
-     * Set a new value in evaluator buffer, and display it in the wxTextCtrl.
+     * Set a new value in evaluator buffer and display it in the wxTextCtrl.
      *
      * @param aValue is the new value to store and display
      * if aValue is empty, the value "0" is stored and displayed
@@ -57,7 +58,7 @@ public:
     void SetValue( const wxString& aValue ) override;
 
 protected:
-    ///< Numeric expression evaluator
+    /// Numeric expression evaluator.
     NUMERIC_EVALUATOR m_eval;
 
     void onTextFocusGet( wxFocusEvent& aEvent );

include/widgets/unit_binder.h

@@ -132,7 +132,7 @@ public:
      * Return the current value in Internal Units.
      *
      * The returned value will be truncated according to the precision set by
-     * SetPrecision() (if not <= 0)
+     * SetPrecision() (if not <= 0).
      */
     virtual double GetDoubleValue();
 
@@ -161,9 +161,9 @@ public:
     /**
      * Validate the control against the given range, informing the user of any errors found.
      *
-     * @param aMin a minimum value for validation
+     * @param aMin a minimum value for validation.
-     * @param aMax a maximum value for validation
+     * @param aMax a maximum value for validation.
-     * @param aUnits the units of the min/max parameters (use UNSCALED for internal units)
+     * @param aUnits the units of the min/max parameters (use UNSCALED for internal units).
      * @return false on error.
      */
     virtual bool Validate( double aMin, double aMax, EDA_UNITS aUnits = EDA_UNITS::UNSCALED );
@@ -178,15 +178,15 @@ public:
     /**
      * Show/hide the label, widget and units label.
      *
-     * @param aShow called for the Show() routine in wx
+     * @param aShow called for the Show() routine in wx.
-     * @param aResize if true, the element will be sized to 0 on hide and -1 on show
+     * @param aResize if true, the element will be sized to 0 on hide and -1 on show.
      */
     void Show( bool aShow, bool aResize = false );
 
     /**
-     * Get the origin transforms coordinate type
+     * Get the origin transforms coordinate type.
      *
-     * @returns the origin transforms coordinate type
+     * @returns the origin transforms coordinate type.
      */
     ORIGIN_TRANSFORMS::COORD_TYPES_T GetCoordType() const
     {
@@ -194,7 +194,7 @@ public:
     }
 
     /**
-     * Set the current origin transform mode
+     * Set the current origin transform mode.
      */
     void SetCoordType( ORIGIN_TRANSFORMS::COORD_TYPES_T aCoordType )
     {
@@ -202,7 +202,7 @@ public:
     }
 
     /**
-     * Force the binder to evaluate the text
+     * Force the binder to evaluate the text.
      */
     void RequireEval()
     {
@@ -239,17 +239,17 @@ protected:
 protected:
     bool                m_bindFocusEvent;
 
-    ///< The bound widgets
+    /// The bound widgets.
     wxStaticText*       m_label;
     wxWindow*           m_valueCtrl;
-    wxStaticText*       m_unitLabel;      ///< Can be nullptr
+    wxStaticText*       m_unitLabel;      ///< Can be nullptr.
 
-    ///< Currently used units.
+    /// Currently used units.
     const EDA_IU_SCALE* m_iuScale;
     EDA_UNITS           m_units;
     bool                m_negativeZero;   ///< Indicates "-0" should be displayed for 0.
     EDA_DATA_TYPE       m_dataType;
-    int                 m_precision;      ///< 0 to 6
+    int                 m_precision;      ///< 0 to 6.
 
     wxString            m_errorMessage;
 
@@ -257,21 +257,21 @@ protected:
     bool                m_allowEval;
     bool                m_needsEval;
 
-    long                m_selStart;       ///< Selection start and end of the original text
+    long                m_selStart;       ///< Selection start and end of the original text.
     long                m_selEnd;
 
-    bool                m_unitsInValue;   ///< Units label should be included in value text
+    bool                m_unitsInValue;   ///< Units label should be included in value text.
 
-    /// A reference to an ORIGIN_TRANSFORMS object
+    /// A reference to an #ORIGIN_TRANSFORMS object.
     ORIGIN_TRANSFORMS&  m_originTransforms;
 
-    /// Type of coordinate for display origin transforms
+    /// Type of coordinate for display origin transforms.
     ORIGIN_TRANSFORMS::COORD_TYPES_T m_coordType;
 };
 
 
 /**
- * Specialization for wxPropertyGrid, where we have no labels and units are displayed in the editor
+ * Specialization for wxPropertyGrid, where we have no labels and units are displayed in the editor.
  */
 class PROPERTY_EDITOR_UNIT_BINDER : public UNIT_BINDER
 {

include/widgets/widget_hotkey_list.h

@@ -42,84 +42,74 @@ class WIDGET_HOTKEY_LIST : public wxTreeListCtrl
 {
 public:
     /**
-     * Constructor WIDGET_HOTKEY_LIST
+     * Create a #WIDGET_HOTKEY_LIST.
-     * Create a WIDGET_HOTKEY_LIST.
      *
-     * @param aParent - parent widget
+     * @param aParent is the parent widget.
-     * @param aHotkeys - EDA_HOTKEY_CONFIG data - a hotkey store is constructed
+     * @param aHotkeys is the #EDA_HOTKEY_CONFIG data: a hotkey store is constructed from this.
-     * from this.
      */
     WIDGET_HOTKEY_LIST( wxWindow* aParent, HOTKEY_STORE& aHotkeyStore, bool aReadOnly );
 
     /**
-     * Method ApplyFilterString
+     * Apply a filter string to the hotkey list, selecting which hotkeys to show.
-     * Apply a filter string to the hotkey list, selecting which hotkeys
-     * to show.
      *
-     * @param aFilterStr the string to filter by
+     * @param aFilterStr the string to filter by.
      */
     void ApplyFilterString( const wxString& aFilterStr );
 
     /**
      * Set hotkeys in the control to default or original values.
+     *
      * @param aResetToDefault if true, reset to the defaults inherent to the hotkeys, else
      *                        reset to the value they had when the dialog was invoked.
      */
     void ResetAllHotkeys( bool aResetToDefault );
 
     /**
-     * Method TransferDataToControl
      * Load the hotkey data from the store into the control.
-     * @return true iff the operation was successful
+     *
+     * @return true if the operation was successful.
      */
     bool TransferDataToControl();
 
     /**
-     * Method TransferDataFromControl
      * Save the hotkey data from the control.
-     * @return true iff the operation was successful
+     *
+     * @return true if the operation was successful.
      */
     bool TransferDataFromControl();
 
     /**
-     * Static method MapKeypressToKeycode
      * Map a keypress event to the correct key code for use as a hotkey.
      */
     static long MapKeypressToKeycode( const wxKeyEvent& aEvent );
 
 protected:
     /**
-     * Method editItem
      * Prompt the user for a new hotkey given a list item.
      */
     void editItem( wxTreeListItem aItem, int aEditId );
 
     /**
-     * Method resetItem
      * Reset the item to either the default, the value when the dialog was opened, or none.
      */
     void resetItem( wxTreeListItem aItem, int aResetId );
 
     /**
-     * Method onActivated
      * Handle activation of a row.
      */
     void onActivated( wxTreeListEvent& aEvent );
 
     /**
-     * Method onContextMenu
      * Handle right-click on a row.
      */
     void onContextMenu( wxTreeListEvent& aEvent );
 
     /**
-     * Method onMenu
      * Handle activation of a context menu item.
      */
     void onMenu( wxCommandEvent& aEvent );
 
     /**
-     * Method resolveKeyConflicts
      * Check if we can set a hotkey, and prompt the user if there is a conflict between keys.
      * The key code should already have been checked that it's not for the same entry as it's
      * current in, or else this method will prompt for the self-change.
@@ -128,29 +118,25 @@ protected:
      * g_CommonSectionTag means the key code must only be checked with the aSectionTag section
      * and g_CommonSectionTag section.
      *
-     * @param aKey - key to check
+     * @param aKey is the key to check.
-     * @param aActionName - name of the action into which the key is proposed to be installed
+     * @param aActionName is the name of the action into which the key is proposed to be installed.
      *
-     * @return true iff the user accepted the overwrite or no conflict existed
+     * @return true if the user accepted the overwrite or no conflict existed.
      */
     bool resolveKeyConflicts( TOOL_ACTION* aAction, long aKey );
 
 private:
     /**
-     * Method getHKClientData
+     * Return the #WIDGET_HOTKEY_CLIENT_DATA for the given item, or NULL if the item is invalid.
-     * Return the WIDGET_HOTKEY_CLIENT_DATA for the given item, or NULL if the item is invalid.
      */
     WIDGET_HOTKEY_CLIENT_DATA* getHKClientData( wxTreeListItem aItem );
 
     /**
-     * Method updateFromClientData
      * Refresh the visible text on the widget from the rows' client data objects.
      */
     void updateFromClientData();
 
     /**
-     * Method updateShownItems
-     *
      * Update the items shown in the widget based on a given filter string.
      *
      * @param aFilterStr the string to filter with. Empty means no filter.
@@ -163,14 +149,14 @@ private:
      * If the hotkey conflicts, the user is prompted to change anyway (and in doing so, unset
      * the conflicting key), or cancel the attempt.
      *
-     * @param aHotkey the change-able hotkey to try to change
+     * @param aHotkey the change-able hotkey to try to change.
-     * @param aKey the key code to change it to
+     * @param aKey the key code to change it to.
-     * @param alternate Change the secondary hotkey
+     * @param alternate Change the secondary hotkey.
      */
     void changeHotkey( HOTKEY& aHotkey, long aKey, bool alternate );
 
     /**
-     * Recalculates column widths after model has changed
+     * Recalculate column widths after model has changed.
      */
     void updateColumnWidths();
 

include/widgets/wx_busy_indicator.h

@@ -31,21 +31,22 @@ class wxBusyCursor;
 
 
 /**
- * Simple wrapper around wxBusyCursor for used with the generic BUSY_INDICATOR
+ * Simple wrapper around wxBusyCursor for used with the generic BUSY_INDICATOR interface.
- * interface. Can be used to provide a WX busy cursor (spinner) to generic code
+ *
- * that otherwise has no concept of wx cursors.
+ * Can be used to provide a WX busy cursor (spinner) to generic code that otherwise has no
+ * concept of wx cursors.
  */
 class WX_BUSY_INDICATOR : public BUSY_INDICATOR
 {
 public:
     /**
-     * Constructs a busy indicator represented by a wxBusyCursor, which will be
+     * Construct a busy indicator represented by a wxBusyCursor, which will be
      * active as long as this object exists (just like wxBustCursor itself).
      */
     WX_BUSY_INDICATOR();
 
 private:
-    ///< This is the actual WX cursor that is the indicator.
+    /// This is the actual WX cursor that is the indicator.
     std::unique_ptr<wxBusyCursor> m_cursor;
 };
 

include/widgets/wx_collapsible_pane.h

@@ -22,15 +22,17 @@
 
 #include <wx/control.h>
 #include <wx/containr.h>
-#include <wx/statbox.h> // needed to provide a hint that wx libraries instantiated wxNavigationEnabled<wxControl>
+#include <wx/statbox.h> // needed to provide a hint that wx libraries instantiated
+                        // wxNavigationEnabled<wxControl>
 
 
 wxDECLARE_EVENT( WX_COLLAPSIBLE_PANE_HEADER_CHANGED, wxCommandEvent );
 wxDECLARE_EVENT( WX_COLLAPSIBLE_PANE_CHANGED, wxCommandEvent );
 
 /**
- * A header control for WX_COLLAPSIBLE_PANE
+ * A header control for #WX_COLLAPSIBLE_PANE.
- * Looks like a static text with a unicode arrow prepended to show the state
+ *
+ * Looks like a static text with a unicode arrow prepended to show the state.
  * Takes the same space as a static text.  This is similar to the wxCollapsiblePane on GTK.
  */
 class WX_COLLAPSIBLE_PANE_HEADER : public wxControl
@@ -96,9 +98,9 @@ private:
 
 /**
  * A better wxCollapsiblePane that
- * - Looks the same on all platforms
+ * - Looks the same on all platforms.
- * - Doesn't have the same sizer bugs
+ * - Doesn't have the same sizer bugs.
- * - Uses proper window colors
+ * - Uses proper window colors.
  */
 class WX_COLLAPSIBLE_PANE : public wxNavigationEnabled<wxControl>
 {

include/widgets/wx_dataviewctrl.h

@@ -24,6 +24,7 @@
 
 /**
  * Extension of the wxDataViewCtrl to include some helper functions for working with items.
+ *
  * These should probably be sent upstream, since they may be useful to others, but for now
  * just extend the class with them ourselves.
  */
@@ -36,7 +37,7 @@ public:
     /**
      * Get the previous item in list order.
      *
-     * @param aItem a valid item in the control's model
+     * @param aItem a valid item in the control's model.
      * @return the item before aItem, or an invalid item if aItem is at the top.
      */
     wxDataViewItem GetPrevItem( wxDataViewItem const& aItem );
@@ -44,7 +45,7 @@ public:
     /**
      * Get the next item in list order.
      *
-     * @param aItem a valid item in the control's model
+     * @param aItem a valid item in the control's model.
      * @return the item after aItem, or an invalid item if aItem is at the bottom.
      */
     wxDataViewItem GetNextItem( wxDataViewItem const& aItem );
@@ -52,7 +53,7 @@ public:
     /**
      * Get the previous sibling of an item.
      *
-     * @param aItem a valid item in the control's model
+     * @param aItem a valid item in the control's model.
      * @return the sibling before aItem, or an invalid item if aItem has no siblings before it.
      */
     wxDataViewItem GetPrevSibling( wxDataViewItem const& aItem );
@@ -60,7 +61,7 @@ public:
     /**
      * Get the next sibling of an item.
      *
-     * @param aItem a valid item in the control's model
+     * @param aItem a valid item in the control's model.
      * @return the sibling after aItem, or an invalid item if aItem has no siblings after it.
      */
     wxDataViewItem GetNextSibling( wxDataViewItem const& aItem );

include/widgets/wx_ellipsized_static_text.h

@@ -29,10 +29,10 @@
 /**
  * A version of a wxStaticText control that will request a smaller size than the full string.
  *
- * This can be used with the ellipsization styles to ensure that the control will actually ellipsize
+ * This can be used with the ellipsization styles to ensure that the control will actually
- * properly inside sizer elements (since they ask for the best size but GTK reports the best size
+ * ellipsize properly inside sizer elements (since they ask for the best size but GTK reports
- * as being the full string length, even when ellipsization is enabled). This work around is discussed
+ * the best size as being the full string length, even when ellipsization is enabled). This work
- * in upstream ticket https://trac.wxwidgets.org/ticket/18992.
+ * around is discussed in upstream ticket https://trac.wxwidgets.org/ticket/18992.
  */
 class WX_ELLIPSIZED_STATIC_TEXT: public wxStaticText
 {
@@ -43,11 +43,12 @@ public:
                                long aStyle = 0 );
 
     /**
-     * Set the string that is used for determining the requested size of the control. The control
+     * Set the string that is used for determining the requested size of the control.
-     * will return this string length from GetBestSize(), regardless of what string the control
-     * is displaying.
      *
-     * @param aString is the smallest string to display without ellipses
+     * The control will return this string length from GetBestSize(), regardless of what string
+     * the control is displaying.
+     *
+     * @param aString is the smallest string to display without ellipses.
      */
     void SetMinimumStringLength( const wxString& aString )
     {
@@ -58,7 +59,7 @@ protected:
     wxSize DoGetBestSize() const override;
 
 private:
-    wxString m_minimumString;  // The string that is used to set the minimum control width
+    wxString m_minimumString;  ///< The string that is used to set the minimum control width.
 };
 
 

include/widgets/wx_grid.h

@@ -60,6 +60,7 @@ public:
     /**
      * Hide wxGrid's SetColLabelSize() method with one which makes sure the size is tall
      * enough for the system GUI font.
+     *
      * @param height
      */
     void SetColLabelSize( int aHeight );        // Yes, we're hiding a non-virtual method
@@ -72,14 +73,15 @@ public:
 
     /**
      * Enable alternate row highlighting, where every odd row has a different background
-     * color than the even rows.s
+     * color than the even rows.
      *
-     * @param aEnable flag to specify to enable alternate row striping in the grid
+     * @param aEnable flag to specify to enable alternate row striping in the grid.
      */
     void EnableAlternateRowColors( bool aEnable = true );
 
     /**
      * Get a tokenized string containing the shown column indexes.
+     *
      * Tokens are separated by spaces.
      */
     wxString GetShownColumnsAsString();
@@ -109,14 +111,16 @@ public:
 
     /**
      * Close any open cell edit controls.
-     * @param aQuietMode if true don't send events (ie: for row/col delete operations)
+     *
-     * @return false if validation failed
+     * @param aQuietMode if true don't send events (ie: for row/col delete operations).
+     * @return false if validation failed.
      */
     bool CommitPendingChanges( bool aQuietMode = false );
     bool CancelPendingChanges();
 
     /**
-     * Set a UNITS_PROVIDER to enable use of unit- and eval-based Getters.
+     * Set a EUNITS_PROVIDER to enable use of unit- and eval-based Getters.
+     *
      * @param aProvider
      */
     void SetUnitsProvider( UNITS_PROVIDER* aProvider, int aCol = 0 );
@@ -125,19 +129,21 @@ public:
 
     /**
      * Apply standard KiCad unit and eval services to a numeric cell.
-     * @param aRow the cell row index to fetch
+     *
-     * @param aCol the cell column index to fetch
+     * @param aRow the cell row index to fetch.
-     * @param aIsOptional if true, indicates to the unit provider the value is optional
+     * @param aCol the cell column index to fetch.
-     * @return the value held by the cell in internal units
+     * @param aIsOptional if true, indicates to the unit provider the value is optional.
+     * @return the value held by the cell in internal units.
      */
     int GetUnitValue( int aRow, int aCol );
 
 
     /**
      * Apply standard KiCad unit and eval services to a numeric cell.
-     * @param aRow the cell row index to fetch
+     *
-     * @param aCol the cell column index to fetch
+     * @param aRow the cell row index to fetch.
-     * @return the value held by the cell in internal units
+     * @param aCol the cell column index to fetch.
+     * @return the value held by the cell in internal units.
      */
     std::optional<int> GetOptionalUnitValue( int aRow, int aCol );
 
@@ -147,32 +153,34 @@ public:
     void SetUnitValue( int aRow, int aCol, int aValue );
 
     /**
-     * Set a unitized cell's optional value
+     * Set a unitized cell's optional value.
      */
     void SetOptionalUnitValue( int aRow, int aCol, std::optional<int> aValue );
 
     /**
-     * Calculates the specified column based on the actual size of the text
+     * Calculate the specified column based on the actual size of the text on screen.
-     * on screen.  Will return the maximum value of all calculated widths.
+     *
-     * @param aCol - Integer value of the column to resize.  Specify -1 for the row labels.
+     * @param aCol is the index of the column to resize.  Specify -1 for the row labels.
-     * @param aHeader - Include the header in the width calculation
+     * @param aHeader is the header in the width calculation.
-     * @param aContents - Include the full contents of the column
+     * @param aContents is the full contents of the column.
-     * @param aKeep - Use the current size as a minimum value
+     * @param aKeep is the current size as a minimum value.
-     * @return The new size of the column
+     * @return The maximum value of all calculated widths.
      */
     int GetVisibleWidth( int aCol, bool aHeader = true, bool aContents = true, bool aKeep = false );
 
     /**
      * Ensure the height of the row displaying the column labels is enough, even
-     * if labels are multiline texts
+     * if labels are multiline texts.
      */
     void EnsureColLabelsVisible();
 
     /**
      * WxWidgets has a bunch of bugs in its handling of wxGrid mouse events which close cell
-     * editors right after opening them.  Helpfully, it already has a bunch of work-arounds in
+     * editors right after opening them.
-     * place (such as the SetInSetFocus() hack), including one to make slow clicks work.  We
+     *
-     * re-purpose this hack to work-around the bugs when we want to open an editor.
+     * Helpfully, it already has a bunch of work-arounds in place (such as the SetInSetFocus()
+     * hack), including one to make slow clicks work.  We re-purpose this hack to work-around
+     * the bugs when we want to open an editor.
      */
     void ShowEditorOnMouseUp() { m_waitForSlowClick = true; }
     void CancelShowEditorOnMouseUp() { m_waitForSlowClick = false; }
@@ -201,6 +209,7 @@ public:
     /**
      * Grids that have column sizes automatically set to fill the available width don't want
      * to shrink afterwards (because wxGrid reports the aggregate column size as the bestSize.
+     *
      * @param aSize
      */
     void OverrideMinSize( double aXPct, double aYPct )
@@ -208,6 +217,7 @@ public:
         wxSize size = DoGetBestSize();
         m_minSizeOverride = wxSize( KiROUND( size.x * aXPct ), KiROUND( size.y * aYPct ) );
     }
+
     wxSize DoGetBestSize() const override
     {
         if( m_minSizeOverride )