Header folder housekeeping.

include/advanced_config.h

@@ -728,12 +728,12 @@ private:
     ADVANCED_CFG();
 
     /**
-     * Load the config from the normal config file
+     * Load the config from the normal configuration file.
      */
     void loadFromConfigFile();
 
-    /*
-     * Load config from the given config base
+    /**
+     * Load config from the given configuration base.
      */
     void loadSettings( wxConfigBase& aCfg );
 };

include/array_axis.h

@@ -43,12 +43,14 @@ public:
     {
         NUMBERING_NUMERIC = 0, ///< Arabic numerals: 0,1,2,3,4,5,6,7,8,9,10,11...
         NUMBERING_HEX,
-        NUMBERING_ALPHA_NO_IOSQXZ, /*!< Alphabet, excluding IOSQXZ
-                                     *
-                                     * Per ASME Y14.35M-1997 sec. 5.2 (previously MIL-STD-100 sec. 406.5)
-                                     * as these can be confused with numerals and are often not used
-                                     * for pin numbering on BGAs, etc
-                                     */
+
+        /**
+         * Alphabet, excluding IOSQXZ
+         *
+         * Per ASME Y14.35M-1997 sec. 5.2 (previously MIL-STD-100 sec. 406.5) as these can be
+         * confused with numerals and are often not used for pin numbering on BGAs, etc.
+         */
+        NUMBERING_ALPHA_NO_IOSQXZ,
         NUMBERING_ALPHA_FULL,      ///< Full 26-character alphabet
     };
 
@@ -56,19 +58,19 @@ public:
 
     /**
      * Get the alphabet for the current numbering scheme.
-     * @param  type the numbering scheme
-     * @return      the alphabet (as a string)
+     * @param  type the numbering scheme.
+     * @return the alphabet (as a string).
      */
     const wxString& GetAlphabet() const;
 
     /**
-     * Set the axis numbering type
+     * Set the axis numbering type.
      */
     void SetAxisType( NUMBERING_TYPE aType );
 
     /**
      * Set the axis start (as a string, which should decode to a valid index
-     * in the alphabet)
+     * in the alphabet),
      */
     bool SetOffset( const wxString& aOffsetName );
 
@@ -76,28 +78,28 @@ public:
      * Set the start offset for the series (e.g. 0 to start at 0/A, 4 to start
      * at 4/E).
      *
-     * @param aOffset offset of the first item in the
+     * @param aOffset offset of the first item in the.
      */
     void SetOffset( int aOffset );
 
     /**
      * Get the numbering offset for the axis
      *
-     * @return       the current offset
+     * @return the current offset.
      */
     int GetOffset() const;
 
     /**
      * Set the skip between consecutive numbers (useful when doing a partial
-     * array, e.g. only one side of a connector)
+     * array, e.g. only one side of a connector).
      */
     void SetStep( int aStep );
 
     /**
      * Get the position number (name) for the n'th axis point
      *
-     * @param  n array point index, from 0
-     * @return   the point's name
+     * @param  n array point index, from 0.
+     * @return the point's name.
      */
     wxString GetItemNumber( int n ) const;
 
@@ -105,16 +107,16 @@ private:
     /**
      * Get the numbering offset for a given numbering string
      *
-     * @param  str   a numbering string, say "B" or "5"
-     * @return       the offset, if found, else empty
+     * @param  str is a numbering string, say "B" or "5".
+     * @return the offset, if found, else empty.
      */
     std::optional<int> getNumberingOffset( const wxString& str ) const;
 
     NUMBERING_TYPE m_type;
     int            m_offset;
 
-    ///< Skip every 'n' numbers
+    /// Skip every 'n' numbers.
     int m_step;
 };
 
-#endif // ARRAY_AXIS__H
+#endif // ARRAY_AXIS__H

include/array_options.h

@@ -31,6 +31,7 @@
 
 /**
  * Options that govern the setup of an "array" of multiple item.
+ *
  * The base #ARRAY_OPTIONS do not encode a specific geometry or numbering
  * method, this is done by derived classes.
  */
@@ -54,7 +55,7 @@ public:
     virtual ~ARRAY_OPTIONS(){};
 
     /**
-     * Transform applied to an object by this array
+     * Transform applied to an object by this array.
      */
     struct TRANSFORM
     {
@@ -63,28 +64,29 @@ public:
     };
 
     /**
-     * Get the transform of the n-th point in the array
-     * @param  aN the index of the array point (0 is the original point)
-     * @param  aPos the existing item position
-     * @return  a transform (an offset and a rotation)
+     * Get the transform of the n-th point in the array.
+     *
+     * @param  aN the index of the array point (0 is the original point).
+     * @param  aPos the existing item position.
+     * @return a transform (an offset and a rotation)/
      */
     virtual TRANSFORM GetTransform( int aN, const VECTOR2I& aPos ) const = 0;
 
     /**
-     * The number of points in this array
+     * The number of points in this array.
      */
     virtual int GetArraySize() const = 0;
 
     /**
-     * Get the position number (name) for the n'th array point
-     * @param  n array point index, from 0 to GetArraySize() - 1
-     * @return   the point's name
+     * Get the position number (name) for the n'th array point.
+     *
+     * @param  n array point index, from 0 to GetArraySize() - 1.
+     * @return the point's name.
      */
     virtual wxString GetItemNumber( int n ) const = 0;
 
-    /*!
-     * @return are the items in this array numbered, or are all the
-     * items numbered the same?
+    /**
+     * @return are the items in this array numbered, or are all the items numbered the same?
      */
     bool ShouldNumberItems() const
     {
@@ -96,7 +98,7 @@ public:
         m_shouldNumber = aShouldNumber;
     }
 
-    /*!
+    /**
      * @return are the footprints in this array reannotated to be unique (true), or do they
      * keep the original annotation (false)?
      */
@@ -110,7 +112,7 @@ public:
         m_reannotateFootprints = aShouldReannotate;
     }
 
-    /*!
+    /**
      * @return is the numbering is enabled and should start at a point
      * specified in these options or is it implicit according to the calling
      * code?
@@ -189,6 +191,7 @@ struct KICOMMON_API ARRAY_CIRCULAR_OPTIONS : public ARRAY_OPTIONS
 
     /// number of point in the array
     long             m_nPts;
+
     /// angle between points, or 0 for each point separated by this value (decideg)
     EDA_ANGLE        m_angle;
     VECTOR2I         m_centre;

include/base_set.h

@@ -212,7 +212,8 @@ public:
     // Define less-than operator for comparison
     bool operator<( const BASE_SET& other ) const
     {
-        return alg::lexicographical_compare_three_way( begin(), end(), other.begin(), other.end() ) < 0;
+        return alg::lexicographical_compare_three_way( begin(), end(), other.begin(),
+                                                       other.end() ) < 0;
     }
 
     /**
@@ -283,10 +284,12 @@ public:
 
     /**
      * Convert the output of FmtHex() and replaces this set's values
-     * with those given in the input string.  Parsing stops at the first
-     * non hex ASCII byte, except that marker bytes output from FmtHex are
-     * not terminators.
-     * @return int - number of bytes consumed
+     * with those given in the input string.
+     *
+     * Parsing stops at the first non hex ASCII byte, except that marker bytes output from
+     * FmtHex() are not terminators.
+     *
+     * @return the number of bytes consumed.
      */
     int ParseHex( const std::string& str )
     {
@@ -295,10 +298,12 @@ public:
 
     /**
      * Convert the output of FmtHex() and replaces this set's values
-     * with those given in the input string.  Parsing stops at the first
-     * non hex ASCII byte, except that marker bytes output from FmtHex are
-     * not terminators.
-     * @return int - number of bytes consumed
+     * with those given in the input string.
+     *
+     * Parsing stops at the first non hex ASCII byte, except that marker bytes output from
+     * FmtHex() are not terminators.
+     *
+     * @return number of bytes consumed.
      */
     int ParseHex( const char* aStart, int aCount )
     {

include/base_units.h

@@ -66,10 +66,10 @@
  * unit used in pcbnew, cvpcb or gerbview (nanometer or deci-mil) depending on compile time option
  */
 
-constexpr double GERB_IU_PER_MM = 1e5; // Gerbview IU is 10 nanometers.
-constexpr double PCB_IU_PER_MM = 1e6;  // Pcbnew IU is 1 nanometer.
-constexpr double PL_IU_PER_MM = 1e3;   // internal units in micron (should be enough)
-constexpr double SCH_IU_PER_MM = 1e4;  // Schematic internal units 1=100nm
+constexpr double GERB_IU_PER_MM = 1e5; ///< Gerbview IU is 10 nanometers.
+constexpr double PCB_IU_PER_MM = 1e6;  ///< Pcbnew IU is 1 nanometer.
+constexpr double PL_IU_PER_MM = 1e3;   ///< Internal units in micron (should be enough).
+constexpr double SCH_IU_PER_MM = 1e4;  ///< Schematic internal units 1=100nm.
 
 struct EDA_IU_SCALE
 {

include/bitmap_base.h

@@ -251,7 +251,7 @@ public:
     void UpdateImageDataBuffer();
 
 private:
-    /*
+    /**
      * Rebuild the internal bitmap used to draw/plot image.
      *
      * This must be called after a #m_image change.
@@ -262,19 +262,18 @@ private:
 
     void updatePPI();
 
-    double    m_scale;              // The scaling factor of the bitmap
-                                    // With m_pixelSizeIu, controls the actual draw size
-    wxMemoryBuffer m_imageData;     // The original image data, in its original format
-    wxBitmapType   m_imageType;     // the image type (png, jpeg, etc.)
-
-    wxImage*  m_image;              // the raw, uncompressed image data
-    wxImage*  m_originalImage;      // Raw image data, not transformed by rotate/mirror
-    wxBitmap* m_bitmap;             // the bitmap used to draw/plot image
-    double    m_pixelSizeIu;        // The scaling factor of the bitmap
-                                    // to convert the bitmap size (in pixels)
-                                    // to internal KiCad units
-                                    // Usually does not change
-    int       m_ppi;                // the bitmap definition. the default is 300PPI
+    double    m_scale;              ///< The scaling factor of the bitmap
+                                    ///< with #m_pixelSizeIu, controls the actual draw size.
+    wxMemoryBuffer m_imageData;     ///< The original image data in its original format.
+    wxBitmapType   m_imageType;     ///< The image type (png, jpeg, etc.).
+
+    wxImage*  m_image;              ///< The raw, uncompressed image data.
+    wxImage*  m_originalImage;      ///< Raw image data, not transformed by rotate/mirror.
+    wxBitmap* m_bitmap;             ///< The bitmap used to draw/plot image.
+    double    m_pixelSizeIu;        ///< The scaling factor of the bitmap to convert the bitmap
+                                    ///< size (in pixels) to internal KiCad units.  This usually
+                                    ///< does not change.
+    int       m_ppi;                ///< The bitmap definition. The default is 300PPI.
     KIID      m_imageId;
     bool      m_isMirroredX;        // Used for OpenGL rendering only
     bool      m_isMirroredY;        // Used for OpenGL rendering only

include/board_design_settings.h

@@ -105,9 +105,9 @@
 #define MINIMUM_LINE_WIDTH_MM         0.005   // minimal line width entered in a dialog
 #define MAXIMUM_LINE_WIDTH_MM         100.0   // max line width entered in a dialog
 
-// Default pad properies
+// Default pad properties
 #define DEFAULT_PAD_WIDTH_MM 2.54         // master pad width
-#define DEFAULT_PAD_HEIGTH_MM 1.27        // master pad heigth
+#define DEFAULT_PAD_HEIGTH_MM 1.27        // master pad height
 #define DEFAULT_PAD_DRILL_DIAMETER_MM 0.8 // master pad drill diameter for PTH
 #define DEFAULT_PAD_REACT_RADIUS 15       // master pad corner radius in percent
 
@@ -476,7 +476,7 @@ public:
      * Sets custom track width for differential pairs (i.e. not available in netclasses or
      * preset list).
      *
-     * @param aDrill is the new track wdith.
+     * @param aDrill is the new track width.
      */
     inline void SetCustomDiffPairWidth( int aWidth )
     {
@@ -619,7 +619,7 @@ public:
     inline int GetBoardThickness() const { return m_boardThickness; }
     inline void SetBoardThickness( int aThickness ) { m_boardThickness = aThickness; }
 
-    /*
+    /**
      * Return an epsilon which accounts for rounding errors, etc.
      *
      * While currently an advanced cfg, going through this API allows us to easily change
@@ -673,8 +673,10 @@ public:
     std::vector<VIA_DIMENSION>       m_ViasDimensionsList;
     std::vector<DIFF_PAIR_DIMENSION> m_DiffPairDimensionsList;
 
-    /** The parameters of teardrops for the different teardrop targets (via/pad, track end)
-     *  3 set of parameters always exist: for round shapes, for rect shapes, for track ends
+    /**
+     * The parameters of teardrops for the different teardrop targets (via/pad, track end).
+     *
+     * 3 set of parameters always exist: for round shapes, for rect shapes, for track ends.
      */
     TEARDROP_PARAMETERS_LIST         m_TeardropParamsList;
 
@@ -799,13 +801,15 @@ private:
     /// This is also the last used netclass after starting a track.
     wxString   m_currentNetClassName;
 
-    /** the description of layers stackup, for board fabrication
-     * only physical layers are in layers stackup.
-     * It includes not only layers enabled for the board edition, but also dielectric layers
+    /**
+     * The description of layers stackup, for board fabrication only physical layers are in
+     * layers stackup.
+     *
+     * It includes not only layers enabled for the board edition, but also dielectric layers.
      */
     BOARD_STACKUP m_stackup;
 
-    /// The default settings that will be used for new zones
+    /// The default settings that will be used for new zones.
     ZONE_SETTINGS m_defaultZoneSettings;
 };
 

include/board_item.h

@@ -140,7 +140,7 @@ public:
      * object.  The scale runs from 0.0 (definitely different objects) to 1.0 (same)
      *
      * This is a pure virtual function.  Derived classes must implement this.
-    */
+     */
     virtual double Similarity( const BOARD_ITEM& aItem ) const = 0;
     virtual bool operator==( const BOARD_ITEM& aItem ) const = 0;
 
@@ -201,12 +201,14 @@ public:
 
     /**
      * Invoke a function on all children.
+     *
      * @note This function should not add or remove items to the parent.
      */
     virtual void RunOnChildren( const std::function<void ( BOARD_ITEM* )>& aFunction ) const { }
 
     /**
      * Invoke a function on all descendants.
+     *
      * @note This function should not add or remove items.
      */
     virtual void RunOnDescendants( const std::function<void ( BOARD_ITEM* )>& aFunction,

include/board_printout.h

@@ -93,31 +93,31 @@ public:
                            int aPageNum = 1, int aPageCount = 1 );
 
 protected:
-    ///< Convert mils to internal units
+    /// Convert mils to internal units.
     virtual int milsToIU( double aMils ) const = 0;
 
-    ///< Enables layers visibility for a printout
+    /// Enable layers visibility for a printout.
     virtual void setupViewLayers( KIGFX::VIEW& aView, const LSET& aLayerSet );
 
-    ///< Configures PAINTER object for a printout
+    /// Configure #PAINTER object for a printout.
     virtual void setupPainter( KIGFX::PAINTER& aPainter );
 
-    ///< Configures GAL object for a printout
+    /// Configure #GAL object for a printout.
     virtual void setupGal( KIGFX::GAL* aGal );
 
-    ///< Returns bounding box of the printed objects (excluding drawing-sheet frame)
+    /// Return bounding box of the printed objects (excluding drawing-sheet frame).
     virtual BOX2I getBoundingBox() = 0;
 
-    ///< Returns a PAINTER instance used to draw the items.
+    /// Return the #PAINTER instance used to draw the items.
     virtual std::unique_ptr<KIGFX::PAINTER> getPainter( KIGFX::GAL* aGal ) = 0;
 
-    ///< Source VIEW object (note that actual printing only refers to this object)
+    /// Source VIEW object (note that actual printing only refers to this object).
     const KIGFX::VIEW* m_view;
 
-    ///< Printout parameters
+    /// Printout parameters.
     BOARD_PRINTOUT_SETTINGS m_settings;
 
-    /// True if the caller is Gerbview, false for Pcbnew
+    /// True if the caller is Gerbview, false for Pcbnew.
     bool  m_gerbviewPrint;
 };
 

include/commit.h

@@ -76,19 +76,19 @@ public:
     COMMIT();
     virtual ~COMMIT();
 
-    ///< Add a new item to the model
+    /// Add a new item to the model.
     COMMIT& Add( EDA_ITEM* aItem, BASE_SCREEN *aScreen = nullptr )
     {
         return Stage( aItem, CHT_ADD, aScreen );
     }
 
-    ///< Notify observers that aItem has been added
+    /// Notify observers that aItem has been added.
     COMMIT& Added( EDA_ITEM* aItem, BASE_SCREEN *aScreen = nullptr )
     {
         return Stage( aItem, CHT_ADD | CHT_DONE, aScreen );
     }
 
-    ///< Remove a new item from the model
+    /// Remove a new item from the model.
     COMMIT& Remove( EDA_ITEM* aItem, BASE_SCREEN *aScreen = nullptr )
     {
         return Stage( aItem, CHT_REMOVE, aScreen );
@@ -100,15 +100,21 @@ public:
         return Stage( aItem, CHT_REMOVE | CHT_DONE, aScreen );
     }
 
-    ///< Modify a given item in the model.
-    ///< Must be called before modification is performed.
+    /**
+     * Modify a given item in the model.
+     *
+     * @note Must be called before modification is performed.
+     */
     COMMIT& Modify( EDA_ITEM* aItem, BASE_SCREEN *aScreen = nullptr )
     {
         return Stage( aItem, CHT_MODIFY, aScreen );
     }
 
-    ///< Create an undo entry for an item that has been already modified. Requires a copy done
-    ///< before the modification.
+    /**
+     * Create an undo entry for an item that has been already modified.
+     *
+     * @note Requires a copy done before the modification.
+     */
     COMMIT& Modified( EDA_ITEM* aItem, EDA_ITEM* aCopy, BASE_SCREEN *aScreen = nullptr )
     {
         return createModified( aItem, aCopy, 0, aScreen );
@@ -124,7 +130,7 @@ public:
         return *this;
     }
 
-    ///< Add a change of the item aItem of type aChangeType to the change list.
+    /// Add a change of the item aItem of type aChangeType to the change list.
     virtual COMMIT& Stage( EDA_ITEM* aItem, CHANGE_TYPE aChangeType,
                            BASE_SCREEN *aScreen = nullptr );
 
@@ -135,10 +141,10 @@ public:
                            UNDO_REDO aModFlag = UNDO_REDO::UNSPECIFIED,
                            BASE_SCREEN *aScreen = nullptr );
 
-    ///< Execute the changes.
+    /// Execute the changes.
     virtual void Push( const wxString& aMessage = wxT( "A commit" ), int aFlags = 0 ) = 0;
 
-    ///< Revert the commit by restoring the modified items state.
+    /// Revert the commit by restoring the modified items state.
     virtual void Revert() = 0;
 
     bool Empty() const
@@ -146,7 +152,7 @@ public:
         return m_changes.empty();
     }
 
-    ///< Returns status of an item.
+    /// Returns status of an item.
     int GetStatus( EDA_ITEM* aItem, BASE_SCREEN *aScreen = nullptr );
 
     EDA_ITEM* GetFirst() const { return m_changes.empty() ? nullptr : m_changes[0].m_item; }
@@ -161,7 +167,7 @@ protected:
         BASE_SCREEN* m_screen;
     };
 
-    // Should be called in Push() & Revert() methods
+    /// Should be called in Push() & Revert() methods
     void clear()
     {
         m_changedItems.clear();

include/ctl_flags.h

@@ -21,27 +21,31 @@
 #pragma once
 
 // These flags are used to control the data items that must be disabled when creating
-// mainly a netlist but also some other kicad files.
+// mainly a netlist but also some other KiCad files.
 // They allow skipping specified data in these files.
 
 #define CTL_OMIT_EXTRA              (1 << 0)
 #define CTL_OMIT_NETS               (1 << 1)
-#define CTL_OMIT_PAD_NETS           (1 << 1)    ///< Omit pads net names (useless in library)
+#define CTL_OMIT_PAD_NETS           (1 << 1)    ///< Omit pads net names (useless in library).
 #define CTL_OMIT_UUIDS              (1 << 2)    ///< Omit component unique ids (useless in library)
-#define CTL_OMIT_FP_UUID            (1 << 3)    ///< Don't prefix the footprint UUID to the sheet path.
-#define CTL_OMIT_PATH               (1 << 4)    ///< Omit component sheet time stamp (useless in library)
+#define CTL_OMIT_FP_UUID            (1 << 3)    ///< Don't prefix the footprint UUID to the sheet
+                                                ///< path.
+#define CTL_OMIT_PATH               (1 << 4)    ///< Omit component sheet time stamp (useless in
+                                                ///< library).
 #define CTL_OMIT_AT                 (1 << 5)    ///< Omit position and rotation. (always saved
                                                 ///< with position 0,0 and rotation = 0 in library).
 
-// If set, when calling EDA_TEXT::Format, disable writing the "hide" keyword in save file
-#define CTL_OMIT_HIDE               (1 << 6)    ///< Omit the hide attribute in .kicad_xxx files
+// If set, when calling EDA_TEXT::Format, disable writing the "hide" keyword in save file.
+#define CTL_OMIT_HIDE               (1 << 6)    ///< Omit the hide attribute in .kicad_xxx files.
 
 #define CTL_OMIT_LIBNAME            (1 << 7)    ///< Omit lib alias when saving (used for
-                                                ///< board/not library).
+                                                ///< board/not library)..
 #define CTL_OMIT_FOOTPRINT_VERSION  (1 << 8)    ///< Omit the version string from the (footprint)
-                                                ///< sexpr group
-#define CTL_OMIT_FILTERS            (1 << 9)    ///< Omit the ki_fp_filters attribute in .kicad_xxx files
-#define CTL_OMIT_INITIAL_COMMENTS   (1 << 10)   ///< omit FOOTPRINT initial comments
+                                                ///< sexpr group.
+#define CTL_OMIT_FILTERS            (1 << 9)    ///< Omit the ki_fp_filters attribute in
+                                                ///< .kicad_xxx files.
+#define CTL_OMIT_INITIAL_COMMENTS   (1 << 10)   ///< Omit #FOOTPRINT initial comments.
 
-#define CTL_OMIT_COLOR              (1 << 11)   ///< Omit the color attribute in .kicad_xxx files
-#define CTL_OMIT_HYPERLINK          (1 << 12)   ///< Omit the hyperlink attribute in .kicad_xxx files
+#define CTL_OMIT_COLOR              (1 << 11)   ///< Omit the color attribute in .kicad_xxx files.
+#define CTL_OMIT_HYPERLINK          (1 << 12)   ///< Omit the hyperlink attribute in .kicad_xxx
+                                                ///< files.

include/design_block_lib_table.h

@@ -53,7 +53,7 @@ public:
     bool operator!=( const DESIGN_BLOCK_LIB_TABLE_ROW& aRow ) const { return !( *this == aRow ); }
 
     /**
-     * return the type of design block library table represented by this row.
+     * Return the type of design block library table represented by this row.
      */
     const wxString GetType() const override { return DESIGN_BLOCK_IO_MGR::ShowType( type ); }
 
@@ -110,14 +110,14 @@ public:
     bool operator!=( const DESIGN_BLOCK_LIB_TABLE& r ) const { return !( *this == r ); }
 
     /**
-     * Return an #DESIGN_BLOCK_LIB_TABLE_ROW if \a aNickName is found in this table or in any chained
-     * fall back table fragment.
+     * Return an #DESIGN_BLOCK_LIB_TABLE_ROW if \a aNickName is found in this table or in any
+     * chained fall back table fragment.
      *
      * If \a aCheckIfEnabled is true, the library will be ignored even if it is disabled.
      * Otherwise, the row found will be returned even if entry is disabled.
      *
-     * The #PLUGIN is loaded and attached to the "plugin" field of the #DESIGN_BLOCK_LIB_TABLE_ROW if
-     * not already loaded.
+     * The #PLUGIN is loaded and attached to the "plugin" field of the #DESIGN_BLOCK_LIB_TABLE_ROW
+     * if not already loaded.
      *
      * @param aNickName is the name of library nickname to find.
      * @param aCheckIfEnabled is the flag to check if the library found is enabled.
@@ -130,7 +130,8 @@ public:
     /**
      * Return a list of design block names contained within the library given by @a aNickname.
      *
-     * @param aDesignBlockNames is the list to fill with the design block names found in \a aNickname
+     * @param aDesignBlockNames is the list to fill with the design block names found in
+     *                          \a aNickname.
      * @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW.
      * @param aBestEfforts if true, don't throw on errors.
      *
@@ -218,7 +219,8 @@ public:
      * @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW.
      * @param aDesignBlockName is the name of a design block to delete from the specified library.
      *
-     * @throw IO_ERROR if there is a problem finding the design block or the library, or deleting it.
+     * @throw IO_ERROR if there is a problem finding the design block or the library, or deleting
+     *        it.
      */
     void DesignBlockDelete( const wxString& aNickname, const wxString& aDesignBlockName );
 
@@ -279,7 +281,7 @@ public:
      * Return the name of the environment variable used to hold the directory of
      * locally installed "KiCad sponsored" system design block libraries.
      *
-     *These can be either legacy or pretty format.  The only thing special about this
+     * These can be either legacy or pretty format.  The only thing special about this
      * particular environment variable is that it is set automatically by KiCad on
      * program start up, <b>if</b> it is not set already in the environment.
      */

include/dpi_scaling.h

@@ -58,43 +58,46 @@ public:
 
     /**
      * Get the content scale factor, which may be different from the scale
-     * factor on some platforms.  This value should be used for scaling
-     * user interface elements (fonts, icons, etc) whereas the scale
-     * factor should be used for scaling canvases.
+     * factor on some platforms.
+     *
+     * This value should be used for scaling user interface elements (fonts, icons, etc) whereas
+     * the scale factor should be used for scaling canvases.
      */
     virtual double GetContentScaleFactor() const = 0;
 
     /**
-     * Is the current value auto scaled, or is it user-set in the config
+     * Is the current value auto scaled or is it user-set in the config.
      */
     virtual bool GetCanvasIsAutoScaled() const = 0;
 
     /**
-     * Set the common DPI config in a given config object
+     * Set the common DPI config in a given config object.
      *
      * The encoding of the automatic/manual nature of the config is handled internally.
      *
-     * @param aAuto   store a value meaning "no user-set scale"
-     * @param aValue  the value to store (ignored if aAuto set)
+     * @param aAuto   store a value meaning "no user-set scale".
+     * @param aValue  the value to store (ignored if aAuto set).
      */
     virtual void SetDpiConfig( bool aAuto, double aValue ) = 0;
 
-    /*
+    /**
      * Get the maximum scaling factor that should be presented to the user.
+     *
      * This is only advisory, it has no real technical use other than for validation.
      */
     static double GetMaxScaleFactor();
 
-    /*
+    /**
      * Get the minimum scaling factor that should be presented to the user.
+     *
      * This is only advisory, it has no real technical use other than for validation.
      */
     static double GetMinScaleFactor();
 
     /**
-     * Get the "default" scaling factor to use if not other config is available
+     * Get the "default" scaling factor to use if not other config is available.
      */
     static double GetDefaultScaleFactor();
 };
 
-#endif // DPI_SCALING__H
+#endif // DPI_SCALING__H

include/dsnlexer.h

@@ -528,17 +528,17 @@ protected:
         return parseDouble( GetTokenText( aToken ) );
     }
 
-    bool                iOwnReaders;            ///< on readerStack, should I delete them?
+    bool                iOwnReaders;            ///< On readerStack, should I delete them?
     const char*         start;
     const char*         next;
     const char*         limit;
-    char                dummy[1];               ///< when there is no reader.
+    char                dummy[1];               ///< When there is no reader.
 
     typedef std::vector<LINE_READER*>  READER_STACK;
 
     READER_STACK        readerStack;            ///< all the LINE_READERs by pointer.
 
-    ///< no ownership. ownership is via readerStack, maybe, if iOwnReaders
+    /// No ownership. ownership is via readerStack, maybe, if #iOwnReaders.
     LINE_READER*        reader;
 
     bool                specctraMode;           ///< if true, then:
@@ -548,19 +548,19 @@ protected:
                                                 ///< else not.
 
     char                stringDelimiter;
-    bool                space_in_quoted_tokens; ///< blank spaces within quoted strings
+    bool                space_in_quoted_tokens; ///< Blank spaces within quoted strings.
 
-    bool                commentsAreTokens;      ///< true if should return comments as tokens
+    bool                commentsAreTokens;      ///< True if should return comments as tokens.
 
-    int                 prevTok;                ///< curTok from previous NextTok() call.
-    int                 curOffset;              ///< offset within current line of the current token
+    int                 prevTok;                ///< #curTok from previous NextTok() call.
+    int                 curOffset;              ///< Offset within current line of the current token
 
-    int                 curTok;                 ///< the current token obtained on last NextTok()
-    std::string         curText;                ///< the text of the current token
+    int                 curTok;                 ///< The current token obtained on last NextTok().
+    std::string         curText;                ///< The text of the current token.
 
-    const KEYWORD*      keywords;               ///< table sorted by CMake for bsearch()
-    unsigned            keywordCount;           ///< count of keywords table
-    const KEYWORD_MAP*  keywordsLookup;         ///< fast, specialized "C string" hashtable
+    const KEYWORD*      keywords;               ///< Table sorted by CMake for bsearch().
+    unsigned            keywordCount;           ///< Count of keywords table.
+    const KEYWORD_MAP*  keywordsLookup;         ///< Fast, specialized "C string" hashtable.
 #endif // SWIG
 };
 

include/eda_base_frame.h

@@ -108,7 +108,7 @@ class EDA_BASE_FRAME : public wxFrame, public TOOLS_HOLDER, public KIWAY_HOLDER,
 {
 public:
     /**
-     * Specifies whether we are interacting with the undo or redo stacks
+     * Specify whether we are interacting with the undo or redo stacks.
      */
     enum UNDO_REDO_LIST
     {
@@ -216,7 +216,7 @@ public:
     void OnPreferences( wxCommandEvent& event );
 
     /**
-     * Displays the preferences and settings of all opened editors paged dialog, starting with
+     * Display the preferences and settings of all opened editors paged dialog, starting with
      * a particular page
      */
     void ShowPreferences( wxString aStartPage, wxString aStartParentPage );
@@ -284,12 +284,13 @@ public:
     void ShowInfoBarMsg( const wxString& aMsg, bool aShowCloseButton = false );
 
     /**
-     * Returns the settings object used in SaveSettings(), and is overloaded in
+     * Return the settings object used in SaveSettings(), and is overloaded in
      * #KICAD_MANAGER_FRAME.
      */
     virtual APP_SETTINGS_BASE* config() const;
 
     void LoadWindowState( const wxString& aFileName );
+
     /**
      * Load window settings from the given settings object.
      *
@@ -332,7 +333,7 @@ public:
     virtual WINDOW_SETTINGS* GetWindowSettings( APP_SETTINGS_BASE* aCfg );
 
     /**
-     * Load frame state info from a configuration file
+     * Load frame state info from a configuration file.
      */
     virtual void LoadWindowState( const WINDOW_STATE& aState );
 
@@ -353,14 +354,15 @@ public:
     }
 
     /**
-     * Save changes to the project local settings.  These settings are used to save/restore the
-     * view state for a specific project, and should never contain design data.  This method is
-     * normally called automatically at various points in the workflow so that the user's most
-     * recent display settings are automatically persisted.
+     * Save changes to the project local settings.
+     *
+     * These settings are used to save/restore the view state for a specific project, and
+     * should never contain design data.  This method is normally called automatically at
+     * various points in the workflow so that the user's most recent display settings are
+     * automatically persisted.
      *
      * The method is virtual so you can override it to call the suitable save method.
      * The base method does nothing.
-     *
      */
     virtual void SaveProjectLocalSettings() {};
 
@@ -375,7 +377,7 @@ public:
                                      const wxString& aDefaultShortname );
 
     /**
-     * Fetches the file name from the file history list.
+     * Fetch the file name from the file history list.
      *
      * This removes the selected file, if this file does not exist.  The menu is also updated,
      * if #FILE_HISTORY::UseMenu was called at initialization time.
@@ -390,7 +392,7 @@ public:
                                  FILE_HISTORY* aFileHistory = nullptr );
 
     /**
-     * Removes all files from the file history.
+     * Remove all files from the file history.
      *
      * @param aFileHistory The FILE_HISTORY in use. If null, the main application file
      *                     history is used
@@ -432,7 +434,7 @@ public:
     virtual wxString GetCurrentFileName() const { return wxEmptyString; }
 
     /**
-     * Recreates the menu bar.
+     * Recreate the menu bar.
      *
      * Needed when the language or icons are changed
      */
@@ -441,12 +443,12 @@ public:
     void SetMenuBar( wxMenuBar *menu_bar ) override;
 
     /**
-     * Adds the standard KiCad help menu to the menubar.
+     * Add the standard KiCad help menu to the menubar.
      */
     void AddStandardHelpMenu( wxMenuBar* aMenuBar );
 
     /**
-     * Checks if \a aFileName can be written.
+     * Check if \a aFileName can be written.
      *
      * The function performs a number of tests on \a aFileName to verify that it can be saved.
      * If \a aFileName defines a path with no file name, them the path is tested for user write
@@ -601,14 +603,15 @@ public:
     virtual void HandleSystemColorChange();
 
     /**
-     * Checks if this frame is ready to accept API commands.
+     * Check if this frame is ready to accept API commands.
+     *
      * A frame might not accept commands if a long-running process is underway, a dialog is open,
      * the user is interacting with a tool, etc.
      */
     virtual bool CanAcceptApiCommands() { return IsEnabled(); }
 
 protected:
-    ///< Default style flags used for wxAUI toolbars.
+    /// Default style flags used for wxAUI toolbars.
     static constexpr int KICAD_AUI_TB_STYLE = wxAUI_TB_DEFAULT_STYLE | wxAUI_TB_PLAIN_BACKGROUND;
 
     virtual void doReCreateMenuBar() {}
@@ -661,7 +664,7 @@ protected:
     virtual void setupUIConditions();
 
     /**
-     * Sets the common key-pair for exiting the application (Ctrl-Q) and ties it
+     * Set the common key-pair for exiting the application (Ctrl-Q) and ties it
      * to the wxID_EXIT event id.
      *
      * This is useful in sub-applications to pass the event up to a non-owning window.
@@ -671,14 +674,16 @@ protected:
     void ensureWindowIsOnScreen();
 
     /**
-     * Saves any design-related project settings associated with this frame.
+     * Save any design-related project settings associated with this frame.
+     *
      * This method should only be called as the result of direct user action, for example from an
      * explicit "Save Project" command or as a consequence of saving a design document.
      */
     virtual void saveProjectSettings() {}
 
     /**
-     * Handles event fired when a file is dropped to the window.
+     * Handle event fired when a file is dropped to the window.
+     *
      * In this base class, stores the path of files accepted.
      * Calls DoWithAcceptedFiles() to execute actions on files.
      */
@@ -689,7 +694,8 @@ protected:
 
     /**
      * Execute action on accepted dropped file.
-     * Called in OnDropFiles and should be populated with
+     *
+     * Called in OnDropFiles() and should be populated with
      * the action to execute in inherited classes.
      */
     virtual void            DoWithAcceptedFiles();
@@ -728,7 +734,7 @@ private:
 
 #ifdef __WXMSW__
     /**
-     * Windows specific override of the wxWidgets message handler for a window
+     * Windows specific override of the wxWidgets message handler for a window.
      */
     WXLRESULT MSWWindowProc( WXUINT message, WXWPARAM wParam, WXLPARAM lParam ) override;
 #endif
@@ -781,7 +787,7 @@ private:
     bool            m_isNonUserClose;
 
     /**
-     * Associates files extensions with action to execute.
+     * Associate file extensions with action to execute.
      */
     std::map<const wxString, TOOL_ACTION*> m_acceptedExts;
 };

include/eda_dde.h

@@ -36,13 +36,13 @@
 
 // TCP/IP ports used by Pcbnew and Eeschema respectively.
 
-///< Pcbnew listens on this port for commands from Eeschema
+/// Pcbnew listens on this port for commands from Eeschema.
 #define KICAD_PCB_PORT_SERVICE_NUMBER   4242
 
-///< Eeschema listens on this port for commands from Pcbnew
+/// Eeschema listens on this port for commands from Pcbnew.
 #define KICAD_SCH_PORT_SERVICE_NUMBER   4243
 
-///< Scripting window listens for commands for other apps
+/// Scripting window listens for commands for other apps.
 #define KICAD_PY_PORT_SERVICE_NUMBER    4244
 
 
@@ -51,7 +51,7 @@
 
 bool SendCommand( int aPort, const std::string& aMessage );
 
-///< Must be called to clean up the socket thread used by SendCommand
+/// Must be called to clean up the socket thread used by SendCommand.
 void SocketCleanup();
 
 #endif    // EDA_DDE_H_

include/eda_draw_frame.h

@@ -105,12 +105,12 @@ public:
     void ReleaseFile();
 
     /**
-     * Toggles the scripting console visibility
+     * Toggle the scripting console visibility.
      */
     void ScriptingConsoleEnableDisable();
 
     /**
-     * Gets the current visibility of the scripting console window
+     * Get the current visibility of the scripting console window.
      */
     bool IsScriptingConsoleVisible();
 
@@ -316,7 +316,7 @@ public:
     void AddStandardSubMenus( TOOL_MENU& aMenu );
 
     /**
-     * Prints the drawing-sheet (frame and title block).
+     * Print the drawing-sheet (frame and title block).
      *
      * @param aScreen screen to draw.
      * @param aProperties Optional properties for text variable resolution.
@@ -326,7 +326,8 @@ public:
      */
     void PrintDrawingSheet( const RENDER_SETTINGS* aSettings, BASE_SCREEN* aScreen,
                             const std::map<wxString, wxString>* aProperties, double aMils2Iu,
-                            const wxString& aFilename, const wxString& aSheetLayer = wxEmptyString );
+                            const wxString& aFilename,
+                            const wxString& aSheetLayer = wxEmptyString );
 
     void DisplayToolMsg( const wxString& msg ) override;
 
@@ -334,6 +335,7 @@ public:
 
     /**
      * Called when modifying the page settings.
+     *
      * In derived classes it can be used to modify parameters like draw area size,
      * and any other local parameter related to the page settings.
      */
@@ -439,7 +441,7 @@ public:
     virtual void ActivateGalCanvas();
 
     /**
-     * Changes the current rendering backend.
+     * Change the current rendering backend.
      */
     virtual void SwitchCanvas( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType );
 
@@ -464,7 +466,7 @@ public:
     }
 
     /**
-     * Returns bbox of document with option to not include some items.
+     * Return bounding box of document with option to not include some items.
      *
      * Used most commonly by "Zoom to Fit" and "Zoom to Objects".  In Eeschema for "Zoom to Fit"
      * it's passed "true" to include drawing sheet border, and "false" by "Zoom To Objects" to
@@ -478,12 +480,12 @@ public:
     virtual const BOX2I GetDocumentExtents( bool aIncludeAllVisible = true ) const;
 
     /**
-     * Rebuild all toolbars, and update the checked state of check tools
+     * Rebuild all toolbars and update the checked state of check tools.
      */
     void RecreateToolbars();
 
     /**
-     * Update toolbars if desired toolbar icon changed
+     * Update toolbars if desired toolbar icon changed.
      */
     void OnToolbarSizeChanged();
 
@@ -508,19 +510,22 @@ public:
     bool SaveCanvasImageToFile( const wxString& aFileName, BITMAP_TYPE aBitmapType );
 
     /**
-     * Handler for activating an API plugin (via toolbar or menu)
+     * Handler for activating an API plugin (via toolbar or menu).
      */
     virtual void OnApiPluginInvoke( wxCommandEvent& aEvent );
 
     virtual PLUGIN_ACTION_SCOPE PluginActionScope() const { return PLUGIN_ACTION_SCOPE::INVALID; }
 
-    static bool IsPluginActionButtonVisible( const PLUGIN_ACTION& aAction, APP_SETTINGS_BASE* aCfg );
+    static bool IsPluginActionButtonVisible( const PLUGIN_ACTION& aAction,
+                                             APP_SETTINGS_BASE* aCfg );
 
     /**
-     * Return ordered list of plugin actions for display in the toolbar
+     * Return ordered list of plugin actions for display in the toolbar.
+     *
      * Must be static at the moment because this needs to be called from the preferences dialog,
      * which can exist without the frame in question actually being created.
-     * @param aCfg is the settings to read the plugin ordering from
+     *
+     * @param aCfg is the settings to read the plugin ordering from.
      */
     static std::vector<const PLUGIN_ACTION*> GetOrderedPluginActions( PLUGIN_ACTION_SCOPE aScope,
         APP_SETTINGS_BASE* aCfg );
@@ -539,19 +544,20 @@ protected:
     std::vector<wxWindow*> findDialogs();
 
     /**
-     * Determines the Canvas type to load (with prompt if required) and initializes m_canvasType
+     * Determine the canvas type to load (with prompt if required) and initializes #m_canvasType.
      */
     virtual void resolveCanvasType();
 
     /**
-     * Returns the canvas type stored in the application settings.
+     * Return the canvas type stored in the application settings.
+     *
      * @param aCfg is the APP_SETTINGS_BASE config storing the canvas type.
      * If nullptr (default) the KifaceSettings() will be used
      */
     EDA_DRAW_PANEL_GAL::GAL_TYPE loadCanvasTypeSetting( APP_SETTINGS_BASE* aCfg = nullptr );
 
     /**
-     * Stores the canvas type in the application settings.
+     * Store the canvas type in the application settings.
      */
     bool saveCanvasTypeSetting( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType );
 
@@ -579,7 +585,8 @@ protected:
                                               // to screens
     bool                 m_polarCoords;       // For those frames that support polar coordinates
 
-    bool                 m_showBorderAndTitleBlock;  // Show the drawing sheet (border & title block).
+    // Show the drawing sheet (border & title block).
+    bool                 m_showBorderAndTitleBlock;
 
     wxChoice*            m_gridSelectBox;
     wxChoice*            m_zoomSelectBox;
@@ -603,17 +610,17 @@ protected:
 
     HOTKEY_CYCLE_POPUP* m_hotkeyPopup;
 
-    ///< The current canvas type.
+    /// The current canvas type.
     EDA_DRAW_PANEL_GAL::GAL_TYPE    m_canvasType;
 
-    static bool m_openGLFailureOccured; ///< Has any failure occured when switching to OpenGL in
+    static bool m_openGLFailureOccured; ///< Has any failure occurred when switching to OpenGL in
                                         ///< any EDA_DRAW_FRAME?
 
 private:
     BASE_SCREEN*                m_currentScreen;      ///< current used SCREEN
     EDA_DRAW_PANEL_GAL*         m_canvas;
 
-    ///< This the frame's interface to setting GAL display options.
+    /// This the frame's interface to setting GAL display options.
     GAL_DISPLAY_OPTIONS_IMPL  m_galDisplayOptions;
 
     int m_lastToolbarIconSize;

include/eda_item.h

@@ -78,7 +78,7 @@ namespace google { namespace protobuf { class Any; } }
  */
 typedef std::function< INSPECT_RESULT ( EDA_ITEM* aItem, void* aTestData ) > INSPECTOR_FUNC;
 
-///< std::function passed to nested users by ref, avoids copying std::function.
+/// std::function passed to nested users by ref, avoids copying std::function.
 typedef const INSPECTOR_FUNC& INSPECTOR;
 
 
@@ -197,6 +197,7 @@ public:
     /**
      * Populate \a aList of #MSG_PANEL_ITEM objects with it's internal state for display
      * purposes.
+     *
      * @param aFrame is the EDA_DRAW_FRAME that displays the message panel
      * @param aList is the list to populate.
      */
@@ -244,7 +245,7 @@ public:
     virtual void     SetPosition( const VECTOR2I& aPos ){};
 
     /**
-     * Similar to GetPosition, but allows items to return their visual center rather
+     * Similar to GetPosition() but allows items to return their visual center rather
      * than their anchor.
      */
     virtual const VECTOR2I GetFocusPosition() const { return GetPosition(); }
@@ -490,14 +491,15 @@ public:
 
 private:
     /**
-     * Run time identification, _keep private_ so it can never be changed after a ctor
-     * sets it.  See comment near SetType() regarding virtual functions.
+     * Run time identification, _keep private_ so it can never be changed after a ctor sets it.
+     *
+     * See comment near SetType() regarding virtual functions.
      */
     KICAD_T        m_structType;
 
 protected:
     EDA_ITEM_FLAGS m_flags;
-    EDA_ITEM*      m_parent; ///< Linked list: Link (parent struct)
+    EDA_ITEM*      m_parent; ///< Linked list: Link (parent struct).
     bool           m_forceVisible;
 };
 

include/eda_pattern_match.h

@@ -38,10 +38,10 @@
 
 static const int EDA_PATTERN_NOT_FOUND = wxNOT_FOUND;
 
-/*
+/**
  * A structure for storing weighted search terms.
  *
- * NOTE: an exact match is scored at 8 * Score while a match at the start of the text is scored
+ * @note An exact match is scored at 8 * Score while a match at the start of the text is scored
  * at 2 * Score.
  */
 struct KICOMMON_API SEARCH_TERM
@@ -58,8 +58,8 @@ struct KICOMMON_API SEARCH_TERM
 };
 
 
-/*
- * Interface for a pattern matcher, for which there are several implementations
+/**
+ * Interface for a pattern matcher for which there are several implementations.
  */
 class KICOMMON_API EDA_PATTERN_MATCH
 {
@@ -83,8 +83,9 @@ public:
     virtual ~EDA_PATTERN_MATCH() {}
 
     /**
-     * Set the pattern against which candidates will be matched. If the pattern
-     * can not be processed, returns false.
+     * Set the pattern against which candidates will be matched.
+     *
+     * @return false if the pattern not be processed.
      */
     virtual bool SetPattern( const wxString& aPattern ) = 0;
 
@@ -94,16 +95,17 @@ public:
     virtual wxString const& GetPattern() const = 0;
 
     /**
-     * Return the location and possibly length of a match iff a given candidate
+     * Return the location and possibly length of a match if a given candidate
      * string matches the set pattern.
-     * Otherwise, return an invalid FIND_RESULT.
+     *
+     * Otherwise, return an invalid #FIND_RESULT.
      */
     virtual FIND_RESULT Find( const wxString& aCandidate ) const = 0;
 };
 
 
-/*
- * Match simple substring
+/**
+ * Match simple substring.
  */
 class KICOMMON_API EDA_PATTERN_MATCH_SUBSTR : public EDA_PATTERN_MATCH
 {
@@ -118,8 +120,8 @@ protected:
 };
 
 
-/*
- * Match regular expression
+/**
+ * Match regular expression.
  */
 class KICOMMON_API EDA_PATTERN_MATCH_REGEX : public EDA_PATTERN_MATCH
 {
@@ -211,25 +213,24 @@ class KICOMMON_API EDA_COMBINED_MATCHER
 public:
     EDA_COMBINED_MATCHER( const wxString& aPattern, COMBINED_MATCHER_CONTEXT aContext );
 
-    /*
+    /**
      * Deleted copy or else we have to implement copy constructors for all EDA_PATTERN_MATCH classes
-     * due to this class' m_matchers member being copied
+     * due to this class' m_matchers member being copied.
      */
     EDA_COMBINED_MATCHER( EDA_COMBINED_MATCHER const& ) = delete;
 
-    /*
+    /**
      * Deleted copy or else we have to implement copy constructors for all EDA_PATTERN_MATCH classes
      * due to this class' m_matchers member being copied
      */
     EDA_COMBINED_MATCHER& operator=( EDA_COMBINED_MATCHER const& ) = delete;
 
-    /*
-     * Look in all existing matchers, return the earliest match of any of
-     * the existing.
+    /**
+     * Look in all existing matchers, return the earliest match of any of the existing.
      *
-     * @param aTerm                 term to look for
-     * @param aMatchersTriggered    out: number of matcher that found the term
-     * @param aPostion              out: where the term was found, or EDA_PATTERN_NOT_FOUND
+     * @param aTerm                 term to look for.
+     * @param aMatchersTriggered    out: number of matcher that found the term.
+     * @param aPostion              out: where the term was found, or #EDA_PATTERN_NOT_FOUND.
      *
      * @return true if any matchers found the term
      */
@@ -244,7 +245,7 @@ public:
     int ScoreTerms( std::vector<SEARCH_TERM>& aWeightedTerms );
 
 private:
-    // Add matcher if it can compile the pattern.
+    /// Add matcher if it can compile the pattern.
     void AddMatcher( const wxString& aPattern, std::unique_ptr<EDA_PATTERN_MATCH> aMatcher );
 
     std::vector<std::unique_ptr<EDA_PATTERN_MATCH>> m_matchers;

include/eda_shape.h

@@ -43,7 +43,7 @@ enum class SHAPE_T : int
 {
     UNDEFINED = -1,
     SEGMENT = 0,
-    RECTANGLE,      /// use RECTANGLE instead of RECT to avoid collision in a Windows header
+    RECTANGLE,      ///< Use RECTANGLE instead of RECT to avoid collision in a Windows header.
     ARC,
     CIRCLE,
     POLY,
@@ -55,13 +55,13 @@ enum class SHAPE_T : int
 enum class FILL_T : int
 {
     NO_FILL = 1,
-    FILLED_SHAPE,               // Fill with object color
-    FILLED_WITH_BG_BODYCOLOR,   // Fill with background body color
-    FILLED_WITH_COLOR           // Fill with a separate color
+    FILLED_SHAPE,               ///< Fill with object color.
+    FILLED_WITH_BG_BODYCOLOR,   //< Fill with background body color.
+    FILLED_WITH_COLOR           //< Fill with a separate color.
 };
 
 
-// Holding struct to keep originating midpoint
+/// Holding struct to keep originating midpoint
 struct ARC_MID
 {
     VECTOR2I mid;
@@ -75,7 +75,7 @@ class EDA_SHAPE : public SERIALIZABLE
 public:
     EDA_SHAPE( SHAPE_T aType, int aLineWidth, FILL_T aFill );
 
-    // Construct an EDA_SHAPE from an abstract SHAPE geometry
+    /// Construct an EDA_SHAPE from an abstract SHAPE geometry.
     EDA_SHAPE( const SHAPE& aShape );
 
     // Do not create a copy constructor & operator=.
@@ -217,6 +217,7 @@ public:
 
     /**
      * Set the end point from the angle center and start.
+     *
      * aAngle is:
      * - clockwise in right-down coordinate system
      * - counter-clockwise in right-up (libedit) coordinate system.
@@ -229,8 +230,9 @@ public:
 
     /**
      * Have the start and end points been swapped since they were set?
-     * @return true if they have
-    */
+     *
+     * @return true if they have.
+     */
     bool EndsSwapped() const { return m_endsSwapped; }
 
     // Some attributes are read only, since they are derived from m_Start, m_End, and m_Angle.
@@ -256,29 +258,32 @@ public:
     void SetArcGeometry( const VECTOR2I& aStart, const VECTOR2I& aMid, const VECTOR2I& aEnd );
 
     /**
-     * Set the data used for mid point caching.  If the controlling points remain constant, then
-     * we keep the midpoint the same as it was when read in.  This minimizes VCS churn
+     * Set the data used for mid point caching.
+     *
+     * If the controlling points remain constant, then we keep the midpoint the same as it was
+     * when read in.  This minimizes VCS churn.
      *
-     * @param aStart Cached start point
-     * @param aMid Cached mid point
-     * @param aEnd Cached end point
-     * @param aCenter Calculated center point using the preceeding three
+     * @param aStart Cached start point.
+     * @param aMid Cached mid point.
+     * @param aEnd Cached end point.
+     * @param aCenter Calculated center point using the preceeding three.
      */
-    void SetCachedArcData( const VECTOR2I& aStart, const VECTOR2I& aMid, const VECTOR2I& aEnd, const VECTOR2I& aCenter );
+    void SetCachedArcData( const VECTOR2I& aStart, const VECTOR2I& aMid, const VECTOR2I& aEnd,
+                           const VECTOR2I& aCenter );
 
     const std::vector<VECTOR2I>& GetBezierPoints() const { return m_bezierPoints; }
 
     /**
-     * Duplicate the list of corners in a std::vector<VECTOR2I>
+     * Duplicate the list of corners in a std::vector<VECTOR2I>.
      *
      * It must be used only to convert the SHAPE_POLY_SET internal corner buffer
      * to a list of VECTOR2Is, and nothing else, because it duplicates the buffer,
-     * that is inefficient to know for instance the corner count
+     * that is inefficient to know for instance the corner count.
      */
     void DupPolyPointsList( std::vector<VECTOR2I>& aBuffer ) const;
 
     /**
-     * @return the number of corners of the polygonal shape
+     * @return the number of corners of the polygonal shape.
      */
     int GetPointCount() const;
 
@@ -287,7 +292,7 @@ public:
     const SHAPE_POLY_SET& GetPolyShape() const { return m_poly; }
 
     /**
-     * @return true if the polygonal shape is valid (has more than 2 points)
+     * @return true if the polygonal shape is valid (has more than 2 points).
      */
     bool IsPolyShapeValid() const;
 
@@ -311,14 +316,16 @@ public:
      * Rebuild the m_bezierPoints vertex list that approximate the Bezier curve by a list of
      * segments.
      *
-     * Has meaning only for BEZIER shape.
+     * Has meaning only for #BEZIER shape.
      *
-     * @param aMinSegLen is the max deviation between the polyline and the curve
+     * @param aMinSegLen is the max deviation between the polyline and the curve.
      */
     void RebuildBezierToSegmentsPointsList( int aMaxError );
 
     /**
-     * Make a set of SHAPE objects representing the EDA_SHAPE.  Caller owns the objects.
+     * Make a set of SHAPE objects representing the #EDA_SHAPE.
+     *
+     * Caller owns the objects.
      *
      * @param aEdgeOnly indicates only edges should be generated (even if 0 width), and no fill
      *                  shapes.
@@ -351,12 +358,14 @@ public:
     int GetRectangleWidth() const;
 
     /**
-     * Convert the shape to a closed polygon.  Circles and arcs are approximated by segments.
+     * Convert the shape to a closed polygon.
+     *
+     * Circles and arcs are approximated by segments.
      *
      * @param aBuffer is a buffer to store the polygon.
      * @param aClearance is the clearance around the pad.
      * @param aError is the maximum deviation from a true arc.
-     * @param aErrorLoc whether any approximation error shoule be placed inside or outside
+     * @param aErrorLoc whether any approximation error should be placed inside or outside
      * @param ignoreLineWidth is used for edge cut items where the line width is only for
      *                        visualization
      */
@@ -399,19 +408,22 @@ protected:
     void calcEdit( const VECTOR2I& aPosition );
 
     /**
-     * Finishes editing the shape.
-     * @param aClosed Should polygon shapes be closed (yes for pcbnew/fpeditor, no for libedit)
+     * Finish editing the shape.
+     *
+     * @param aClosed Should polygon shapes be closed (yes for pcbnew/fpeditor, no for libedit).
      */
     void endEdit( bool aClosed = true );
     void setEditState( int aState ) { m_editState = aState; }
 
     /**
-     * Make a set of SHAPE objects representing the EDA_SHAPE.  Caller owns the objects.
+     * Make a set of #SHAPE objects representing the #EDA_SHAPE.
+     *
+     * Caller owns the objects.
      *
      * @param aEdgeOnly indicates only edges should be generated (even if 0 width), and no fill
      *                  shapes.
-     * @param aLineChainOnly indicates SHAPE_POLY_SET is being abused slightly to represent a
-     *                       lineChain rather than a closed polygon
+     * @param aLineChainOnly indicates #SHAPE_POLY_SET is being abused slightly to represent a
+     *                       lineChain rather than a closed polygon.
      */
     // fixme: move to shape_compound
     std::vector<SHAPE*> makeEffectiveShapes( bool aEdgeOnly, bool aLineChainOnly = false ) const;

include/eda_tools.h

@@ -35,7 +35,7 @@
 #include <wx/filename.h>
 
 /**
- * Enumeration of tools
+ * Enumeration of tools.
  */
 enum class EDA_TOOLS
 {
@@ -43,12 +43,13 @@ enum class EDA_TOOLS
 };
 
 /**
- * Check if aFileName is a aTool file
- * As an example, can be used to check if a .sch file is an EAGLE file
- * (may be a legacy KICAD file)
- * @param aFileName name of file to check. Must be given with full path
- * @param aTool EDA tool
- * @return true if the file is an EDA_TOOL file type, false if not or file does not exist
+ * Check if \a aFileName is a \a aTool file.
+ *
+ * As an example, can be used to check if a .sch file is an EAGLE file (may be a legacy KICAD file).
+ *
+ * @param aFileName name of file to check. Must be given with full path.
+ * @param aTool EDA tool.
+ * @return true if the file is an EDA_TOOL file type, false if not or file does not exist.
  */
 bool IsFileFromEDATool( const wxFileName& aFileName, const EDA_TOOLS aTool );
 

include/eda_units.h

@@ -71,8 +71,9 @@ namespace EDA_UNIT_UTILS
     KICOMMON_API int Mils2mm( double aVal );
 
     /**
-     * Writes any unit info found in the string to aUnits.
-     * @return true - when unit was found, false - when unit could not be determined
+     * Write any unit info found in the string to \a aUnits.
+     *
+     * @return true  when unit was found or false when unit could not be determined.
      */
     KICOMMON_API bool FetchUnitsFromString( const wxString& aTextValue, EDA_UNITS& aUnits );
 
@@ -82,10 +83,11 @@ namespace EDA_UNIT_UTILS
      * This version is for appending to a value string.
      *
      * @param aUnits The units requested.
-     * @param aType DISTANCE, AREA, or VOLUME
+     * @param aType DISTANCE, AREA, or VOLUME.
      * @return The human readable units string with appropriate separators.
      */
-    KICOMMON_API wxString GetText( EDA_UNITS aUnits, EDA_DATA_TYPE aType = EDA_DATA_TYPE::DISTANCE );
+    KICOMMON_API wxString GetText( EDA_UNITS aUnits,
+                                   EDA_DATA_TYPE aType = EDA_DATA_TYPE::DISTANCE );
 
     /**
      * Get the units string for a given units type.
@@ -100,9 +102,9 @@ namespace EDA_UNIT_UTILS
                                     EDA_DATA_TYPE aType = EDA_DATA_TYPE::DISTANCE );
 
     /**
-     * Converts \a aAngle from board units to a string appropriate for writing to file.
+     * Convert \a aAngle from board units to a string appropriate for writing to file.
      *
-     * This should only be used for writing to files  as it ignores locale
+     * This should only be used for writing to files  as it ignores locale.
      *
      * @note Internal angles for board items can be either degrees or tenths of degree
      *       on how KiCad is built.
@@ -114,7 +116,7 @@ namespace EDA_UNIT_UTILS
     /**
      * Converts \a aValue from internal units to a string appropriate for writing to file.
      *
-     * This should only be used for writing to files as it ignores locale
+     * This should only be used for writing to files as it ignores locale.
      *
      * @note Internal units for board items can be either deci-mils or nanometers depending
      *       on how KiCad is built.
@@ -128,9 +130,9 @@ namespace EDA_UNIT_UTILS
 
 #if 0   // No support for std::from_chars on MacOS yet
     /**
-     * Converts \a aInput string to internal units when reading from a file.
+     * Convert \a aInput string to internal units when reading from a file.
      *
-     * This should only be used for reading from files as it ignores locale
+     * This should only be used for reading from files as it ignores locale.
      *
      * @param aInput is std::string to parse.
      * @param aIuScale is the scale to use.
@@ -163,28 +165,28 @@ namespace EDA_UNIT_UTILS
     namespace UI
     {
         /**
-         * Function To_User_Unit
-         * convert \a aValue in internal units to the appropriate user units defined by \a aUnit.
+         * Convert \a aValue in internal units to the appropriate user units defined by \a aUnit.
          *
-         * @return The converted value, in double
          * @param aUnit The units to convert \a aValue to.
          * @param aValue The value in internal units to convert.
+         * @return The converted value, in double.
          */
         KICOMMON_API double ToUserUnit( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnit,
                                         double aValue );
 
         /**
-         * Returns the string from \a aValue according to \a aUnits (inch, mm ...) for display.
+         * Return the string from \a aValue according to \a aUnits (inch, mm ...) for display.
          *
          * For readability, if the mantissa has 3 or more digits then any trailing 0's are removed.
          * This function should be used to display values in dialogs because a value entered in mm
          * (for instance 2.0 mm) could need up to 8 digits mantissa to preserve precision.
          *
-         * @param aUnits Units (INCHES, MILLIMETRE ..)
-         * @param aValue Value in internal units
-         * @param aAddUnitsText Add units text with appropriate separators
-         * @param aType DISTANCE, AREA, or VOLUME
-         * @return A wxString object containing value and optionally the symbol unit (like 2.000 mm)
+         * @param aUnits Units (INCHES, MILLIMETRE ..).
+         * @param aValue Value in internal units.
+         * @param aAddUnitsText Add units text with appropriate separators.
+         * @param aType DISTANCE, AREA, or VOLUME.
+         * @return A wxString object containing value and optionally the symbol unit
+         *         (like 2.000 mm).
          */
         KICOMMON_API wxString StringFromValue( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnits,
                                                double aValue,
@@ -199,10 +201,10 @@ namespace EDA_UNIT_UTILS
          * because the mantissa of the number displayed has 4 digits max for readability.  The
          * actual internal value could need up to 8 digits to preserve precision.
          *
-         * @param aUnits Units (INCHES, MILLIMETRE ..)
+         * @param aUnits Units (INCHES, MILLIMETRE ..).
          * @param aValue The double value to convert.
-         * @param aAddUnitsText If true, adds the unit label to the end of the string
-         * @param aType DISTANCE, AREA, or VOLUME
+         * @param aAddUnitsText If true, adds the unit label to the end of the string.
+         * @param aType DISTANCE, AREA, or VOLUME.
          * @return The converted string for display in user interface elements.
          */
         KICOMMON_API wxString MessageTextFromValue( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnits,
@@ -225,21 +227,21 @@ namespace EDA_UNIT_UTILS
                                                         const MINOPTMAX<int>& aValue );
         /**
          * Return in internal units the value \a aValue given in a real unit such as "in", "mm",
-         * or "deg"
+         * or "deg".
          */
         KICOMMON_API double FromUserUnit( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnit,
                                           double aValue );
 
 
         /**
-         * Function DoubleValueFromString
-         * converts \a aTextValue to a double
-         * @warning This utilizes the current locale and will break if decimal formats differ
+         * Convert \a aTextValue to a double.
+         *
+         * @warning This utilizes the current locale and will break if decimal formats differ.
          *
          * @param aIuScale The internal units scale for the current frame/app.
          * @param aUnits The units of \a aTextValue.
          * @param aTextValue A reference to a wxString object containing the string to convert.
-         * @return A double representing that value in internal units
+         * @return A double representing that value in internal units.
          */
         KICOMMON_API double DoubleValueFromString( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnits,
                                                    const wxString& aTextValue,
@@ -248,14 +250,14 @@ namespace EDA_UNIT_UTILS
         KICOMMON_API double DoubleValueFromString( const wxString& aTextValue );
 
         /**
-         * Function ValueFromString
-         * converts \a aTextValue in \a aUnits to internal units used by the application.
+         * Convert \a aTextValue in \a aUnits to internal units used by the application.
+         *
          * @warning This utilizes the current locale and will break if decimal formats differ
          *
          * @param aIuScale The internal units scale for the current frame/app.
          * @param aUnits The units of \a aTextValue.
          * @param aTextValue A reference to a wxString object containing the string to convert.
-         * @return A long long int representing that value in internal units
+         * @return A long long int representing that value in internal units.
          */
         KICOMMON_API long long int ValueFromString( const EDA_IU_SCALE& aIuScale, EDA_UNITS aUnits,
                                                     const wxString& aTextValue,

include/embedded_files.h

@@ -84,12 +84,12 @@ public:
 
     enum class RETURN_CODE : int
     {
-        OK,                  // Success
-        FILE_NOT_FOUND,      // File not found on disk
-        PERMISSIONS_ERROR,   // Could not read/write file
-        FILE_ALREADY_EXISTS, // File already exists in the collection
-        OUT_OF_MEMORY,       // Could not allocate memory
-        CHECKSUM_ERROR,      // Checksum in file does not match data
+        OK,                  ///< Success.
+        FILE_NOT_FOUND,      ///< File not found on disk.
+        PERMISSIONS_ERROR,   ///< Could not read/write file.
+        FILE_ALREADY_EXISTS, ///< File already exists in the collection.
+        OUT_OF_MEMORY,       ///< Could not allocate memory.
+        CHECKSUM_ERROR,      ///< Checksum in file does not match data.
     };
 
     EMBEDDED_FILES() = default;
@@ -101,37 +101,41 @@ public:
     }
 
     /**
-     * Loads a file from disk and adds it to the collection.
+     * Load a file from disk and adds it to the collection.
+     *
      * @param aName is the name of the file to load.
      * @param aOverwrite is true if the file should be overwritten if it already exists.
     */
     EMBEDDED_FILE* AddFile( const wxFileName& aName, bool aOverwrite );
 
     /**
-     * Appends a file to the collection.
-    */
+     * Append a file to the collection.
+     */
     void AddFile( EMBEDDED_FILE* aFile );
 
     /**
-     * Removes a file from the collection and frees the memory.
+     * Remove a file from the collection and frees the memory.
+     *
      * @param aName is the name of the file to remove.
-    */
+     */
     void RemoveFile( const wxString& name, bool aErase = true );
 
     /**
      * Output formatter for the embedded files.
+     *
      * @param aOut is the output formatter.
      * @param aWriteData is true if the actual data should be written.  This is false when writing
      *                   an element that is already embedded in a file that itself has embedded
-     *                   files (boards, schematics, etc.)
-    */
+     *                   files (boards, schematics, etc.).
+     */
     void WriteEmbeddedFiles( OUTPUTFORMATTER& aOut, bool aWriteData ) const;
 
     /**
-     * Returns the link for an embedded file.
+     * Return the link for an embedded file.
+     *
      * @param aFile is the file to get the link for.
      * @return the link for the file to be used in a hyperlink.
-    */
+     */
     wxString GetEmbeddedFileLink( const EMBEDDED_FILE& aFile ) const
     {
         return aFile.GetLink();
@@ -152,42 +156,43 @@ public:
     /**
      * Helper function to get a list of fonts for fontconfig to add to the library.
      *
-     * This is neccesary because EMBEDDED_FILES lives in common at the moment and
+     * This is necessary because EMBEDDED_FILES lives in common at the moment and
      * fontconfig is in libkicommon.  This will create the cache files in the KiCad
      * cache directory (if they do not already exist) and return the temp files names
-    */
+     */
     const std::vector<wxString>* UpdateFontFiles();
 
     /**
      * If we just need the cached version of the font files, we can use this function which
      * is const and will not update the font files.
-    */
+     */
     const std::vector<wxString>* GetFontFiles() const;
 
     /**
-     * Removes all embedded fonts from the collection
-    */
+     * Remove all embedded fonts from the collection.
+     */
     void ClearEmbeddedFonts();
 
     /**
-     * Takes data from the #decompressedData buffer and compresses it using ZSTD
-     * into the #compressedEncodedData buffer. The data is then Base64 encoded.
+     * Take data from the #decompressedData buffer and compresses it using ZSTD
+     * into the #compressedEncodedData buffer.
      *
-     * This call is used when adding a new file to the collection from disk
-    */
+     * The data is then Base64 encoded.  This call is used when adding a new file to the
+     * collection from disk.
+     */
     static RETURN_CODE  CompressAndEncode( EMBEDDED_FILE& aFile );
 
     /**
      * Takes data from the #compressedEncodedData buffer and Base64 decodes it.
-     * The data is then decompressed using ZSTD and stored in the #decompressedData buffer.
      *
+     * The data is then decompressed using ZSTD and stored in the #decompressedData buffer.
      * This call is used when loading the embedded files using the parsers.
-    */
+     */
     static RETURN_CODE  DecompressAndDecode( EMBEDDED_FILE& aFile );
 
     /**
      * Returns the embedded file with the given name or nullptr if it does not exist.
-    */
+     */
     EMBEDDED_FILE* GetEmbeddedFile( const wxString& aName ) const
     {
         auto it = m_files.find( aName );
@@ -237,7 +242,7 @@ private:
     std::vector<wxString>              m_fontFiles;
 
 protected:
-    bool m_embedFonts = false; // If set, fonts will be embedded in the element on save
-                               // Otherwise, font files embedded in the element will be
-                               // removed on save
+    bool m_embedFonts = false; ///< If set, fonts will be embedded in the element on save.
+                               ///< Otherwise, font files embedded in the element will be
+                               ///< removed on save.
 };

include/enum_vector.h

@@ -26,9 +26,10 @@
 #include <type_traits>
 
 /**
- * Macro to create const vectors containing enum values to enable easy iteration. Do not use in new
- * code. Use the DEFINE_ENUM_CLASS_WITH_ITERATOR and DECLARE_ENUM_CLASS_ITERATOR macros instead
- * (unless they don't work ;) ).
+ * Macro to create const vectors containing enum values to enable easy iteration.
+ *
+ * @warning Do not use in new code. Use the #DEFINE_ENUM_CLASS_WITH_ITERATOR and
+ *          #DECLARE_ENUM_CLASS_ITERATOR macros instead (unless they don't work ;) ).
  *
  * Usage:
  * [header]

include/env_paths.h

@@ -21,7 +21,10 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-///< Helper functions to substitute paths with environmental variables.
+/**
+ * @file env_paths.h
+ * @brief Helper functions to substitute paths with environmental variables.
+ */
 
 #ifndef ENV_PATHS_H
 #define ENV_PATHS_H
@@ -62,9 +65,9 @@ wxString NormalizePath( const wxFileName& aFilePath, const ENV_VAR_MAP* aEnvVars
  * @param aFileName is the name of the searched file. It might be a relative path.
  * @param aEnvVars is an optional map of environmental variables that can contain paths.
  * @param aProject is an optional project, to check the project path.
- * @return Full path (apth and file name) if the file was found in one of the paths, otherwise
+ * @return Full path (path and file name) if the file was found in one of the paths, otherwise
  *         an empty string.
-*/
+ */
 wxString ResolveFile( const wxString& aFileName, const ENV_VAR_MAP* aEnvVars,
                       const PROJECT* aProject );
 

include/env_vars.h

@@ -19,7 +19,8 @@
 
 /**
  * @file env_vars.h
- * Functions related to environment variables, including help functions
+ *
+ * Functions related to environment variables, including help functions.
  */
 
 #ifndef ENV_VARS_H
@@ -41,8 +42,9 @@ namespace ENV_VAR
      * Determine if an environment variable is "predefined", i.e. if the
      * name of the variable is special to KiCad, and isn't just a user-specified
      * substitution name.
-     * @param  aEnvVar the variable to check
-     * @return         true if predefined
+     *
+     * @param  aEnvVar the variable to check.
+     * @return         true if predefined.
      */
     KICOMMON_API bool IsEnvVarImmutable( const wxString& aEnvVar );
 
@@ -52,39 +54,43 @@ namespace ENV_VAR
     KICOMMON_API const ENV_VAR_LIST& GetPredefinedEnvVars();
 
     /**
-     * Constructs a versioned environment variable based on this KiCad major version
-     * @param aBaseName is the suffix, like TEMPLATE_DIR
-     * @return an environment variable name, like KICAD8_TEMPLATE_DIR
+     * Construct a versioned environment variable based on this KiCad major version.
+     *
+     * @param aBaseName is the suffix, like TEMPLATE_DIR.
+     * @return an environment variable name, like KICAD8_TEMPLATE_DIR.
      */
     KICOMMON_API wxString GetVersionedEnvVarName( const wxString& aBaseName );
 
     /**
-     * Attempts to retrieve the value of a versioned environment variable, such as
-     * KICAD8_TEMPLATE_DIR.  If this value exists in the map, it will be returned.  If not, the
-     * map will be searched for keys matching KICAD*_<aBaseName>, and the first match's value will
-     * be returned.  If there are no matches, std::nullopt will be returned.
-     * @param aMap is an ENV_VAR_MAP (@see environment.h)
-     * @param aBaseName is the suffix for the environment variable (@see GetVersionedEnvVarName)
+     * Attempt to retrieve the value of a versioned environment variable, such as
+     * KICAD8_TEMPLATE_DIR.
+     *
+     * If this value exists in the map, it will be returned.  If not, the map will be searched
+     * for keys matching KICAD*_<aBaseName>, and the first match's value will be returned.  If
+     * there are no matches, std::nullopt will be returned.
+     *
+     * @param aMap is an #ENV_VAR_MAP (@see environment.h).
+     * @param aBaseName is the suffix for the environment variable (@see GetVersionedEnvVarName).
      */
-    KICOMMON_API std::optional<wxString> GetVersionedEnvVarValue( const std::map<wxString, ENV_VAR_ITEM>& aMap,
-                                                                  const wxString& aBaseName );
+    KICOMMON_API std::optional<wxString>
+                 GetVersionedEnvVarValue( const std::map<wxString, ENV_VAR_ITEM>& aMap,
+                                          const wxString&                         aBaseName );
 
     /**
      * Look up long-form help text for a given environment variable.
      *
-     * This is intended for use in more verbose help resources (as opposed to
-     * tooltip text)
+     * This is intended for use in more verbose help resources (as opposed to tooltip text).
      *
-     * @param  aEnvVar The variable to look up
+     * @param  aEnvVar The variable to look up.
      * @return         A string with help for that variable. Empty if
      *                 no help available for this variable.
      */
     KICOMMON_API wxString LookUpEnvVarHelp( const wxString& aEnvVar );
 
     /**
-     * Get an environment variable as a specific type, if set correctly
+     * Get an environment variable as a specific type, if set correctly.
      *
-     * @param aEnvVarName the name of the environment variable
+     * @param aEnvVarName the name of the environment variable.
      * @return an std::optional containing the value, if set and parseable, otherwise empty.
      */
     template <typename VAL_TYPE>
@@ -100,7 +106,7 @@ namespace ENV_VAR
     KICOMMON_API std::optional<wxString> GetEnvVar( const wxString& aEnvVarName );
 
     /**
-     * Get a double from an environment variable, if set
+     * Get a double from an environment variable, if set.
      *
      * @param aEnvVarName the name of the environment variable
      * @return an std::optional containing the value, if set and parseable as a double,

include/filename_resolver.h

@@ -40,10 +40,10 @@ class EMBEDDED_FILES;
 
 struct SEARCH_PATH
 {
-    wxString m_Alias;           // alias to the base path
-    wxString m_Pathvar;         // base path as stored in the config file
-    wxString m_Pathexp;         // expanded base path
-    wxString m_Description;     // description of the aliased path
+    wxString m_Alias;           ///< Alias to the base path.
+    wxString m_Pathvar;         ///< Base path as stored in the configuration file.
+    wxString m_Pathexp;         ///< Expanded base path.
+    wxString m_Description;     ///< Description of the aliased path.
 };
 
 
@@ -70,10 +70,10 @@ public:
     /**
      * Set the current KiCad project directory as the first entry in the model path list.
      *
-     * @param[in]   aProjDir    current project directory
-     * @param[out]  flgChanged  optional, set to true if directory was changed
-     * @retval      true        success
-     * @retval      false       failure
+     * @param[in]   aProjDir    current project directory.
+     * @param[out]  flgChanged  optional, set to true if directory was changed.
+     * @retval      true        success.
+     * @retval      false       failure.
      */
     bool SetProject( PROJECT* aProject, bool* flgChanged = nullptr );
 
@@ -92,15 +92,15 @@ public:
     bool UpdatePathList( const std::vector<SEARCH_PATH>& aPathList );
 
     /**
-     * Determines the full path of the given file name.
+     * Determine the full path of the given file name.
      *
      * In the future remote files may be supported, in which case it is best to require a full
      * URI in which case ResolvePath should check that the URI conforms to RFC-2396 and related
      * documents and copies \a aFileName into aResolvedName if the URI is valid.
      *
-     * @param aFileName The configured file path to resolve
-     * @param aWorkingPath The current working path for relative path resolutions
-     * @param aFiles The embedded files object to use for embedded file resolution
+     * @param aFileName The configured file path to resolve.
+     * @param aWorkingPath The current working path for relative path resolutions.
+     * @param aFiles The embedded files object to use for embedded file resolution.
      */
     wxString ResolvePath( const wxString& aFileName, const wxString& aWorkingPath,
                           const EMBEDDED_FILES* aFiles );
@@ -130,7 +130,7 @@ public:
     bool SplitAlias( const wxString& aFileName, wxString& anAlias, wxString& aRelPath ) const;
 
     /**
-     * Returns true if the given path is a valid aliased relative path.
+     * Return true if the given path is a valid aliased relative path.
      *
      * If the path contains an alias then hasAlias is set true.
      */
@@ -145,8 +145,8 @@ public:
 
 private:
     /**
-     * Build the path list using available information such as KICAD7_3DMODEL_DIR and the 3d_path_list
-     * configuration file.
+     * Build the path list using available information such as KICAD7_3DMODEL_DIR and the
+     * 3d_path_list configuration file.
      *
      * @warning Invalid paths are silently discarded and removed from the configuration file.
      *
@@ -168,8 +168,8 @@ private:
      */
     void checkEnvVarPath( const wxString& aPath );
 
-    wxString               m_configDir;     // 3D configuration directory
-    std::list<SEARCH_PATH> m_paths;         // list of base paths to search from
+    wxString               m_configDir;     ///< 3D configuration directory.
+    std::list<SEARCH_PATH> m_paths;         ///< List of base paths to search from.
     int                    m_errflags;
     PGM_BASE*              m_pgm;
     PROJECT*               m_project;

include/filter_reader.h

@@ -69,7 +69,7 @@ class WHITESPACE_FILTER_READER : public LINE_READER
 {
 public:
     /**
-     * Doe not take ownership over @a aReader, so will not destroy it.
+     * Do not take ownership over @a aReader, so will not destroy it.
      */
     WHITESPACE_FILTER_READER( LINE_READER& aReader );
 

include/gal_display_options_common.h

@@ -39,25 +39,28 @@ public:
     GAL_DISPLAY_OPTIONS_IMPL();
 
     /**
-         * Read GAL config options from application-level config
-         * @param aCfg      the window settings to load from
-         */
+     * Read GAL config options from application-level config.
+     *
+     * @param aCfg      the window settings to load from.
+     */
     void ReadWindowSettings( WINDOW_SETTINGS& aCfg );
 
     /**
-         * Read GAL config options from the common config store
-         * @param aCommonSettings the common config store
-         * @param aWindow         the wx parent window (used for DPI scaling)
-         */
+     * Read GAL config options from the common config store.
+     *
+     * @param aCommonSettings the common config store.
+     * @param aWindow         the wx parent window (used for DPI scaling).
+     */
     void ReadCommonConfig( COMMON_SETTINGS& aCommonSettings, wxWindow* aWindow );
 
     /**
-         * Read application and common configs
-         * @param aCommonConfig the common config store
-         * @param aCfg          the application config base
-         * @param aBaseName     the application's GAL options key prefix
-         * @param aWindow       the wx parent window (used for DPI scaling)
-         */
+     * Read application and common configs.
+     *
+     * @param aCommonConfig the common config store.
+     * @param aCfg          the application config base.
+     * @param aBaseName     the application's GAL options key prefix.
+     * @param aWindow       the wx parent window (used for DPI scaling).
+     */
     void ReadConfig( COMMON_SETTINGS& aCommonConfig, WINDOW_SETTINGS& aWindowConfig,
                      wxWindow* aWindow );
 

include/gbr_metadata.h

@@ -63,6 +63,7 @@ enum GBR_NC_STRING_FORMAT       // Options for string format in some attribute s
     GBR_NC_STRING_FORMAT_GBRJOB,
     GBR_NC_STRING_FORMAT_NCDRILL
 };
+
 wxString GbrMakeCreationDateAttributeString( GBR_NC_STRING_FORMAT aFormat );
 
 
@@ -91,76 +92,76 @@ public:
     enum GBR_APERTURE_ATTRIB
     {
         GBR_APERTURE_ATTRIB_NONE,           ///< uninitialized attribute.
-        GBR_APERTURE_ATTRIB_ETCHEDCMP,      ///< aperture used for etched components.
+        GBR_APERTURE_ATTRIB_ETCHEDCMP,      ///< Aperture used for etched components.
 
-        ///< aperture used for connected items like tracks (not vias).
+        /// Aperture used for connected items like tracks (not vias).
         GBR_APERTURE_ATTRIB_CONDUCTOR,
-        GBR_APERTURE_ATTRIB_EDGECUT,        ///< aperture used for board cutout,
+        GBR_APERTURE_ATTRIB_EDGECUT,        ///< Aperture used for board cutout,
 
-        ///< aperture used for not connected items (texts, outlines on copper).
+        /// Aperture used for not connected items (texts, outlines on copper).
         GBR_APERTURE_ATTRIB_NONCONDUCTOR,
-        GBR_APERTURE_ATTRIB_VIAPAD,         ///< aperture used for vias.
+        GBR_APERTURE_ATTRIB_VIAPAD,         ///< Aperture used for vias.
 
-        ///< aperture used for through hole component on outer layer.
+        /// Aperture used for through hole component on outer layer.
         GBR_APERTURE_ATTRIB_COMPONENTPAD,
 
-        ///< aperture used for SMD pad. Excluded BGA pads which have their own type.
+        /// Aperture used for SMD pad. Excluded BGA pads which have their own type.
         GBR_APERTURE_ATTRIB_SMDPAD_SMDEF,
 
-        ///< aperture used for SMD pad with a solder mask defined by the solder mask.
+        /// Aperture used for SMD pad with a solder mask defined by the solder mask.
         GBR_APERTURE_ATTRIB_SMDPAD_CUDEF,
 
-        ///< aperture used for BGA pads with a solder mask defined by the copper shape.
+        /// Aperture used for BGA pads with a solder mask defined by the copper shape.
         GBR_APERTURE_ATTRIB_BGAPAD_SMDEF,
 
-        ///< aperture used for BGA pad with a solder mask defined by the solder mask.
+        /// Aperture used for BGA pad with a solder mask defined by the solder mask.
         GBR_APERTURE_ATTRIB_BGAPAD_CUDEF,
 
-        ///< aperture used for edge connector pad (outer layers).
+        /// Aperture used for edge connector pad (outer layers).
         GBR_APERTURE_ATTRIB_CONNECTORPAD,
-        GBR_APERTURE_ATTRIB_WASHERPAD,      ///< aperture used for mechanical pads (NPTH).
-        GBR_APERTURE_ATTRIB_TESTPOINT,      ///< aperture used for test point pad (outer layers).
+        GBR_APERTURE_ATTRIB_WASHERPAD,      ///< Aperture used for mechanical pads (NPTH).
+        GBR_APERTURE_ATTRIB_TESTPOINT,      ///< Aperture used for test point pad (outer layers).
 
-        ///< aperture used for fiducial pad (outer layers), at board level.
+        /// Aperture used for fiducial pad (outer layers), at board level.
         GBR_APERTURE_ATTRIB_FIDUCIAL_GLBL,
 
-        ///< aperture used for fiducial pad (outer layers), at footprint level.
+        /// Aperture used for fiducial pad (outer layers), at footprint level.
         GBR_APERTURE_ATTRIB_FIDUCIAL_LOCAL,
 
-        ///< aperture used for heat sink pad (typically for SMDs).
+        /// Aperture used for heat sink pad (typically for SMDs).
         GBR_APERTURE_ATTRIB_HEATSINKPAD,
 
-        ///< aperture used for castellated pads in copper layer files.
+        /// Aperture used for castellated pads in copper layer files.
         GBR_APERTURE_ATTRIB_CASTELLATEDPAD,
 
-        ///< aperture used for castellated pads in drill files.
+        /// Aperture used for castellated pads in drill files.
         GBR_APERTURE_ATTRIB_CASTELLATEDDRILL,
 
-        GBR_APERTURE_ATTRIB_VIADRILL,       ///< aperture used for via holes in drill files.
-        GBR_APERTURE_ATTRIB_CMP_DRILL,      ///< aperture used for pad holes in drill files.
+        GBR_APERTURE_ATTRIB_VIADRILL,       ///< Aperture used for via holes in drill files.
+        GBR_APERTURE_ATTRIB_CMP_DRILL,      ///< Aperture used for pad holes in drill files.
 
-        ///< aperture used for pads oblong holes in drill files.
+        /// Aperture used for pads oblong holes in drill files.
         GBR_APERTURE_ATTRIB_CMP_OBLONG_DRILL,
 
-        ///< aperture used for flashed cmp position in placement files.
+        /// Aperture used for flashed cmp position in placement files.
         GBR_APERTURE_ATTRIB_CMP_POSITION,
 
-        ///< aperture used for flashed pin 1 (or A1 or AA1) position in placement files.
+        /// Aperture used for flashed pin 1 (or A1 or AA1) position in placement files.
         GBR_APERTURE_ATTRIB_PAD1_POS,
 
-        ///< aperture used for flashed pads position in placement files.
+        /// Aperture used for flashed pads position in placement files.
         GBR_APERTURE_ATTRIB_PADOTHER_POS,
 
-        ///< aperture used to draw component physical body outline without pins in placement files.
+        /// Aperture used to draw component physical body outline without pins in placement files.
         GBR_APERTURE_ATTRIB_CMP_BODY,
 
-        ///< aperture used to draw component physical body outline with pins in placement files.
+        /// Aperture used to draw component physical body outline with pins in placement files.
         GBR_APERTURE_ATTRIB_CMP_LEAD2LEAD,
 
-        ///< aperture used to draw component footprint bounding box in placement files.
+        /// Aperture used to draw component footprint bounding box in placement files.
         GBR_APERTURE_ATTRIB_CMP_FOOTPRINT,
 
-        ///< aperture used to draw component outline courtyard in placement files.
+        /// Aperture used to draw component outline courtyard in placement files.
         GBR_APERTURE_ATTRIB_CMP_COURTYARD,
         GBR_APERTURE_ATTRIB_END             ///< sentinel: max value
     };

include/gestfich.h

@@ -45,29 +45,32 @@ class EDA_LIST_DIALOG;
  * Run the PDF viewer and display a PDF file.
  *
  * @param file the PDF file to open.
- * @return true is success or false if no PDF viewer found.
+ * @retval true if PDF viewer found.
+ * @retval false if no PDF viewer found.
  */
 KICOMMON_API bool OpenPDF( const wxString& file );
 
 /**
  * @param aSrcPath is the full filename of the source.
- * @param aDestPath is the full filename of the target
- * @param aErrors a wxString to *append* any errors to
+ * @param[in] aDestPath is the full filename of the target.
+ * @param[out] aErrors a wxString to *append* any errors to.
  */
 KICOMMON_API void KiCopyFile( const wxString& aSrcPath, const wxString& aDestPath,
                               wxString& aErrors );
 
 /**
  * Call the executable file \a aEditorName with the parameter \a aFileName.
- * @param aEditorName is the full filename for the binary.
- * @param aFileName is the full filename of the file to open.
- * @param aCallback a wxProcess* for the call.
+ *
+ * @param[in] aEditorName is the full filename for the binary.
+ * @param[in] aFileName is the full filename of the file to open.
+ * @param[in] aCallback a wxProcess* for the call.
  * @param aFileForKicad a boolean to flag if aFileName runs with a KiCad binary.
  * In this case aFileName is a shortname and FindKicadFile() is called to return the path.
  * In the other case, aFileName is a full file name (passed prefixed with the path).
  */
-KICOMMON_API int ExecuteFile( const wxString& aEditorName, const wxString& aFileName = wxEmptyString,
-                 wxProcess* aCallback = nullptr, bool aFileForKicad = true );
+KICOMMON_API int ExecuteFile( const wxString& aEditorName,
+                              const wxString& aFileName = wxEmptyString,
+                              wxProcess* aCallback = nullptr, bool aFileForKicad = true );
 
 /**
  * Add un " to the start and the end of string (if not already done).
@@ -102,8 +105,8 @@ KICOMMON_API extern wxString QuoteFullPath( wxFileName& fn, wxPathFormat format
 
 
 /**
- * Removes the directory \a aDirName and all its contents including
- * subdirectories and their files
+ * Remove the directory \a aDirName and all its contents including
+ * subdirectories and their files.
  */
 KICOMMON_API bool RmDirRecursive( const wxString& aDirName, wxString* aErrors = nullptr );
 

include/hash_eda.h

@@ -28,6 +28,7 @@
 #define HASH_EDA_H_
 
 /**
+ * @file hash_eda.h
  * @brief Hashing functions for EDA_ITEMs.
  */
 
@@ -36,15 +37,19 @@
 
 class EDA_ITEM;
 
-///< Enables/disables properties that will be used for calculating the hash.
-///< The properties might be combined using the bitwise 'or' operator.
+/**
+ * Enable/disable properties that will be used for calculating the hash.
+ *
+ * The properties might be combined using the bitwise 'or' operator.
+ */
 enum HASH_FLAGS
 {
     HASH_POS    = 0x01,
 
-    ///< use coordinates relative to the parent object
+    /// Use coordinates relative to the parent object.
     REL_COORD   = 0x02,
-    ///< use coordinates relative to the shape position
+
+    /// Use coordinates relative to the shape position.
     REL_POS     = 0x04,
     HASH_ROT    = 0x08,
     HASH_LAYER  = 0x10,

include/hotkeys_basic.h

@@ -65,9 +65,10 @@ int KeyCodeFromKeyName( const wxString& keyname );
 wxString KeyNameFromKeyCode( int aKeycode, bool* aIsFound = nullptr );
 
 /**
- * In menus we can add a hot key, or an accelerator, or sometimes just a comment.   Hot keys
- * can perform actions using the current mouse cursor position and accelerators perform the
- * same action as the associated menu.
+ * In menus we can add a hot key, or an accelerator, or sometimes just a comment.
+ *
+ * Hot keys can perform actions using the current mouse cursor position and accelerators perform
+ * the same action as the associated menu.
  *
  * A comment is used in tool tips for some tools (zoom ..) to show the hot key that performs
  * this action
@@ -84,8 +85,7 @@ enum HOTKEY_ACTION_TYPE
  * @param aStyle #IS_HOTKEY to add <tab><keyname> (shortcuts in menus, same as hotkeys).
  *               #IS_COMMENT to add <spaces><(keyname)> mainly in tool tips.
  */
-wxString AddHotkeyName(  const wxString& aText, int aHotKey,
-                         HOTKEY_ACTION_TYPE aStyle = IS_HOTKEY);
+wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE aStyle = IS_HOTKEY );
 
 /**
  * Display the current hotkey list.
@@ -97,7 +97,7 @@ wxString AddHotkeyName(  const wxString& aText, int aHotKey,
 void DisplayHotkeyList( EDA_BASE_FRAME* aFrame );
 
 /**
- * Reads a hotkey config file into a map.
+ * Read a hotkey config file into a map.
  *
  * If \a aFileName is empty it will read in the default hotkeys file.
  */
@@ -105,7 +105,7 @@ void ReadHotKeyConfig( const wxString&                             aFileName,
                        std::map<std::string, std::pair<int, int>>& aHotKeys );
 
 /**
- * Reads a hotkey config file into a list of actions
+ * Read a hotkey config file into a list of actions.
  *
  * If \a aFileName is empty it will read in the default hotkeys file.
  */

include/id.h

@@ -25,16 +25,8 @@
 
 /**
  * @file id.h
- */
-
-
-#ifndef ID_H_
-#define ID_H_
-
-#include <wx/defs.h>
-
-/**
- * Common command IDs shared by more than one of the KiCad applications.
+ *
+ * @brief Common command IDs shared by more than one of the KiCad applications.
  *
  * Only place command IDs used in base window class event tables or shared
  * across multiple applications such as the zoom, grid, and language IDs.
@@ -58,6 +50,12 @@
  * Please, change these values if needed
  */
 
+
+#ifndef ID_H_
+#define ID_H_
+
+#include <wx/defs.h>
+
 // Define room for IDs, for each sub application
 #define ROOM_FOR_KICADMANAGER 50
 #define ROOM_FOR_3D_VIEWER 100
@@ -185,9 +183,11 @@ enum main_id
     ID_KICAD_PANEL_PREV_MODEL_START,
     ID_KICAD_PANEL_PREV_MODEL_END = ID_KICAD_PANEL_PREV_MODEL_START + ROOM_FOR_PANEL_PREV_MODEL,
 
-    // Reseve ID for popup menus, when we need to know a menu item is inside a popup menu
+    // Reserve ID for popup menus, when we need to know a menu item is inside a popup menu
     ID_POPUP_MENU_START,
-    // The extra here need to minimum be larger than MAX_BUS_UNFOLD_MENU_ITEMS + MAX_UNIT_COUNT_PER_PACKAGE
+
+    // The extra here need to minimum be larger than MAX_BUS_UNFOLD_MENU_ITEMS +
+    // MAX_UNIT_COUNT_PER_PACKAGE.
     // These values are stored in eeschema_id.h
     ID_POPUP_MENU_END = ID_POPUP_MENU_START + 2048,
 

include/ki_any.h

@@ -17,7 +17,8 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-// This code is a modified version of the GCC standard library implementation (see original licence below):
+// This code is a modified version of the GCC standard library implementation (see original
+// licence below):
 
 // Copyright (C) 2014-2024 Free Software Foundation, Inc.
 //
@@ -42,13 +43,16 @@
 // <http://www.gnu.org/licenses/>.
 
 
-/** An implementation of std::any_cast, which uses type_info::hash_code to check validity of
-  * cast types. This is required as Clang compares types as being equivalent based on their
-  * type_info pointer locations. These are not guaranteed to be the same with identical types
-  * linked in multiple targets from shared libraries. The current Clang implementation of
-  * type_info::hash_code is based on the type names, which should be consistent across translation
-  * units.
-  */
+/**
+ * @file ki_any.h
+ * @brief An implementation of std::any_cast, which uses type_info::hash_code to check validity of
+ *        cast types.
+ *
+ * This is required as Clang compares types as being equivalent based on their type_info pointer
+ * locations. These are not guaranteed to be the same with identical types linked in multiple
+ * targets from shared libraries. The current Clang implementation of type_info::hash_code is
+ * based on the type names, which should be consistent across translation units.
+ */
 #ifndef INCLUDE_KI_ANY_H_
 #define INCLUDE_KI_ANY_H_
 
@@ -71,7 +75,7 @@ template <typename T>
 inline constexpr bool is_in_place_type_v<std::in_place_type_t<T>> = true;
 
 /**
- * @brief Exception class thrown by a failed @c any_cast
+ * Exception class thrown by a failed @c any_cast
  */
 class bad_any_cast final : public std::bad_cast
 {
@@ -80,11 +84,11 @@ public:
 };
 
 /**
-   *  @brief A type-safe container of any type.
-   *
-   *  An `any` object's state is either empty or it stores a contained object
-   *  of CopyConstructible type.
-   */
+ * A type-safe container of any type.
+ *
+ * An `any` object's state is either empty or it stores a contained object
+ * of CopyConstructible type.
+ */
 class any
 {
     // Holds either a pointer to a heap object or the contained object itself
@@ -118,7 +122,7 @@ class any
     template <typename T, typename V = std::decay_t<T>>
     using decay_if_not_any = std::enable_if_t<!std::is_same_v<V, any>, V>;
 
-    /// @brief Emplace with an object created from @p args as the contained object
+    /// Emplace with an object created from @p args as the contained object.
     template <typename T, typename... Args, typename Mgr = Manager<T>>
     void do_emplace( Args&&... args )
     {
@@ -127,7 +131,7 @@ class any
         m_manager = &Mgr::m_manage_fn;
     }
 
-    /// @brief Emplace with an object created from @p il and @p args as the contained object
+    /// Emplace with an object created from @p il and @p args as the contained object.
     template <typename T, typename U, typename... Args, typename Mgr = Manager<T>>
     void do_emplace( std::initializer_list<U> il, Args&&... args )
     {
@@ -148,10 +152,10 @@ class any
     using any_emplace_t = typename any_constructible<V&, V, Args...>::type;
 
 public:
-    /// @brief Default constructor, creates an empty object
+    /// Default constructor, creates an empty object.
     constexpr any() noexcept : m_manager( nullptr ) {}
 
-    /// @brief Copy constructor, copies the state of @p other
+    /// Copy constructor, copies the state of @p other.
     any( const any& other )
     {
         if( !other.has_value() )
@@ -166,7 +170,7 @@ public:
         }
     }
 
-    /// @brief Move constructor, transfer the state from @p other
+    /// Move constructor, transfer the state from @p other.
     any( any&& other ) noexcept
     {
         if( !other.has_value() )
@@ -181,7 +185,7 @@ public:
         }
     }
 
-    /// @brief Construct with a copy of @p value as the contained object
+    /// Construct with a copy of @p value as the contained object.
     template <typename T, typename V = decay_if_not_any<T>, typename Mgr = Manager<V>,
               std::enable_if_t<std::is_copy_constructible_v<V> && !is_in_place_type_v<V>, bool> =
                       true>
@@ -191,7 +195,7 @@ public:
         Mgr::do_create( m_storage, std::forward<T>( value ) );
     }
 
-    /// @brief Construct with an object created from @p args as the contained object
+    /// Construct with an object created from @p args as the contained object.
     template <typename T, typename... Args, typename V = std::decay_t<T>, typename Mgr = Manager<V>,
               any_constructible_t<V, Args&&...> = false>
     explicit any( std::in_place_type_t<T>, Args&&... args ) : m_manager( &Mgr::m_manage_fn )
@@ -199,7 +203,7 @@ public:
         Mgr::do_create( m_storage, std::forward<Args>( args )... );
     }
 
-    /// @brief Construct with an object created from @p il and @p args as the contained object
+    /// Construct with an object created from @p il and @p args as the contained object.
     template <typename T, typename U, typename... Args, typename V = std::decay_t<T>,
               typename Mgr = Manager<V>,
               any_constructible_t<V, std::initializer_list<U>&, Args&&...> = false>
@@ -209,17 +213,17 @@ public:
         Mgr::do_create( m_storage, il, std::forward<Args>( args )... );
     }
 
-    /// @brief Destructor, calls @c reset()
+    /// Destructor, calls @c reset().
     ~any() { reset(); }
 
-    /// @brief Copy the state of another object
+    /// Copy the state of another object.
     any& operator=( const any& rhs )
     {
         *this = any( rhs );
         return *this;
     }
 
-    /// @brief Move assignment operator
+    /// Move assignment operator.
     any& operator=( any&& rhs ) noexcept
     {
         if( !rhs.has_value() )
@@ -237,7 +241,7 @@ public:
         return *this;
     }
 
-    /// Store a copy of @p rhs as the contained object
+    /// Store a copy of @p rhs as the contained object.
     template <typename T>
     std::enable_if_t<std::is_copy_constructible_v<decay_if_not_any<T>>, any&> operator=( T&& rhs )
     {
@@ -245,7 +249,7 @@ public:
         return *this;
     }
 
-    /// Emplace with an object created from @p args as the contained object
+    /// Emplace with an object created from @p args as the contained object.
     template <typename T, typename... Args>
     any_emplace_t<std::decay_t<T>, Args...> emplace( Args&&... args )
     {
@@ -254,7 +258,7 @@ public:
         return *any::Manager<V>::do_access( m_storage );
     }
 
-    /// Emplace with an object created from @p il and @p args as the contained object
+    /// Emplace with an object created from @p il and @p args as the contained object.
     template <typename T, typename U, typename... Args>
     any_emplace_t<std::decay_t<T>, std::initializer_list<U>&, Args&&...>
     emplace( std::initializer_list<U> il, Args&&... args )
@@ -264,7 +268,7 @@ public:
         return *any::Manager<V>::do_access( m_storage );
     }
 
-    /// If not empty, destroys the contained object
+    /// If not empty, destroys the contained object.
     void reset() noexcept
     {
         if( has_value() )
@@ -274,7 +278,7 @@ public:
         }
     }
 
-    /// Exchange state with another object
+    /// Exchange state with another object.
     void swap( any& rhs ) noexcept
     {
         if( !has_value() && !rhs.has_value() )
@@ -304,11 +308,11 @@ public:
         }
     }
 
-    /// Reports whether there is a contained object or not
+    /// Report whether there is a contained object or not.
     bool has_value() const noexcept { return m_manager != nullptr; }
 
 
-    /// The @c typeid of the contained object, or @c typeid(void) if empty
+    /// The @c typeid of the contained object, or @c typeid(void) if empty.
     const std::type_info& type() const noexcept
     {
         if( !has_value() )
@@ -404,13 +408,13 @@ private:
     };
 };
 
-/// Exchange the states of two @c any objects
+/// Exchange the states of two @c any objects.
 inline void swap( any& x, any& y ) noexcept
 {
     x.swap( y );
 }
 
-/// Create a `any` holding a `T` constructed from `args...`
+/// Create a `any` holding a `T` constructed from `args...`.
 template <typename T, typename... Args>
 std::enable_if_t<std::is_constructible_v<any, std::in_place_type_t<T>, Args...>, any>
 make_any( Args&&... args )
@@ -429,15 +433,15 @@ make_any( std::initializer_list<U> il, Args&&... args )
 }
 
 /**
-   * @brief Access the contained object
-   *
-   * @tparam  ValueType  A const-reference or CopyConstructible type.
-   * @param   any        The object to access.
-   * @return  The contained object.
-   * @throw   bad_any_cast If <code>
-   *          any.type() != typeid(remove_reference_t<ValueType>)
-   *          </code>
-   */
+ * Access the contained object.
+ *
+ * @tparam  ValueType  A const-reference or CopyConstructible type.
+ * @param   any        The object to access.
+ * @return  The contained object.
+ * @throw   bad_any_cast If <code>
+ *          any.type() != typeid(remove_reference_t<ValueType>)
+ *          </code>
+ */
 template <typename ValueType>
 ValueType any_cast( const any& any )
 {
@@ -457,16 +461,16 @@ ValueType any_cast( const any& any )
 }
 
 /**
-   * @brief Access the contained object.
-   *
-   * @tparam  ValueType  A reference or CopyConstructible type.
-   * @param   any        The object to access.
-   * @return  The contained object.
-   * @throw   bad_any_cast If <code>
-   *          any.type() != typeid(remove_reference_t<ValueType>)
-   *          </code>
-   * @{
-   */
+ * Access the contained object.
+ *
+ * @tparam  ValueType  A reference or CopyConstructible type.
+ * @param   any        The object to access.
+ * @return  The contained object.
+ * @throw   bad_any_cast If <code>
+ *          any.type() != typeid(remove_reference_t<ValueType>)
+ *          </code>
+ * @{
+ */
 template <typename ValueType>
 ValueType any_cast( any& any )
 {
@@ -535,16 +539,16 @@ void* any_caster( const any* any )
 /// @endcond
 
 /**
-   * @brief Access the contained object.
-   *
-   * @tparam  ValueType  The type of the contained object.
-   * @param   any       A pointer to the object to access.
-   * @return  The address of the contained object if <code>
-   *          any != nullptr && any.type() == typeid(ValueType)
-   *          </code>, otherwise a null pointer.
-   *
-   * @{
-   */
+ * Access the contained object.
+ *
+ * @tparam  ValueType  The type of the contained object.
+ * @param   any       A pointer to the object to access.
+ * @return  The address of the contained object if <code>
+ *          any != nullptr && any.type() == typeid(ValueType)
+ *          </code>, otherwise a null pointer.
+ *
+ * @{
+ */
 template <typename ValueType>
 const ValueType* any_cast( const any* any ) noexcept
 {

include/kidialog.h

@@ -56,10 +56,10 @@ public:
         return wxRichMessageDialog::SetOKCancelLabels( ok, cancel );
     }
 
-    ///< Shows the 'do not show again' checkbox
+    /// Shows the 'do not show again' checkbox.
     void DoNotShowCheckbox( wxString file, int line );
 
-    ///< Checks the 'do not show again' setting for the dialog
+    /// Checks the 'do not show again' setting for the dialog.
     bool DoNotShowAgain() const;
     void ForceShowAgain();
 

include/kiway_player.h

@@ -178,7 +178,7 @@ public:
 
 protected:
 
-    /// event handler, routes to derivative specific virtual KiwayMailIn()
+    /// Event handler, routes to derivative specific virtual #KiwayMailIn().
     void kiway_express( KIWAY_EXPRESS& aEvent );
 
     /**
@@ -189,14 +189,14 @@ protected:
     // variables for modal behavior support, only used by a few derivatives.
     bool            m_modal;        // true if frame is intended to be modal, not modeless
 
-    ///< Points to nested event_loop. NULL means not modal and dismissed.
+    /// Points to nested event_loop. NULL means not modal and dismissed.
     wxGUIEventLoop* m_modal_loop;
     wxWindow*       m_modal_resultant_parent; // the window caller in modal mode
     wxString        m_modal_string;
     bool            m_modal_ret_val;    // true if a selection was made
 
     wxSocketServer*             m_socketServer;
-    std::vector<wxSocketBase*>  m_sockets;         ///< interprocess communication
+    std::vector<wxSocketBase*>  m_sockets;         /// Interprocess communication.
 
 #ifndef SWIG
     DECLARE_EVENT_TABLE()

include/layer_ids.h

@@ -53,7 +53,7 @@
 /**
  * This is the definition of all layers used in Pcbnew.
  *
- * The PCB layer types are fixed at value 0 through LAYER_ID_COUNT to ensure compatibility
+ * The PCB layer types are fixed at value 0 through #LAYER_ID_COUNT to ensure compatibility
  * with legacy board files.
  */
 enum PCB_LAYER_ID: int
@@ -141,27 +141,25 @@ constexpr PCB_LAYER_ID PCBNEW_LAYER_ID_START = F_Cu;
 
 /**
  * Enum used during connectivity building to ensure we do not query connectivity while building
- * the database
+ * the database.
  */
 enum class FLASHING
 {
-    DEFAULT,                // Flashing follows connectivity
-    ALWAYS_FLASHED,         // Always flashed for connectivity
-    NEVER_FLASHED,          // Never flashed for connectivity
+    DEFAULT,                ///< Flashing follows connectivity.
+    ALWAYS_FLASHED,         ///< Always flashed for connectivity.
+    NEVER_FLASHED,          ///< Never flashed for connectivity.
 };
 
-/// Dedicated layers for net names used in Pcbnew
+/// Dedicated layers for net names used in Pcbnew.
 enum NETNAMES_LAYER_ID: int
 {
 
     NETNAMES_LAYER_ID_START = PCB_LAYER_ID_COUNT,
 
-    /// Reserved space for board layer netnames
-
+    /// Reserved space for board layer netnames.
     NETNAMES_LAYER_ID_RESERVED = NETNAMES_LAYER_ID_START + PCB_LAYER_ID_COUNT,
 
-    /// Additional netnames layers (not associated with a PCB layer)
-
+    /// Additional netnames layers (not associated with a PCB layer).
     LAYER_PAD_FR_NETNAMES,
     LAYER_PAD_BK_NETNAMES,
     LAYER_PAD_NETNAMES,
@@ -177,100 +175,134 @@ enum NETNAMES_LAYER_ID: int
 
 /**
  *  GAL layers are "virtual" layers, i.e. not tied into design data.
+ *
  *  Some layers here are shared between applications.
  *
- *  NOTE: Be very careful where you add new layers here.  Layers up to GAL_LAYER_ID_BITMASK_END
+ *  @note Be very careful where you add new layers here.  Layers up to #GAL_LAYER_ID_BITMASK_END
  *  must never be re-ordered and new layers must always be added after this value, because the
  *  layers before this value are mapped to bit locations in legacy board files.
  *
  *  The values in this enum that are used to store visibility state are explicitly encoded with an
- *  offset from GAL_LAYER_ID_START, which is explicitly encoded itself. The exact value of
- *  GAL_LAYER_ID_START is not that sensitive, but the offsets should never be changed or else any
+ *  offset from #GAL_LAYER_ID_START, which is explicitly encoded itself. The exact value of
+ *  #GAL_LAYER_ID_START is not that sensitive, but the offsets should never be changed or else any
  *  existing visibility settings will be disrupted.
  */
 enum GAL_LAYER_ID: int
 {
     GAL_LAYER_ID_START = NETNAMES_LAYER_ID_END,
 
-    LAYER_VIAS               = GAL_LAYER_ID_START +  0, ///< Meta control for all vias opacity/visibility
-    LAYER_VIA_MICROVIA       = GAL_LAYER_ID_START +  1, ///< to draw micro vias
-    LAYER_VIA_BBLIND         = GAL_LAYER_ID_START +  2, ///< to draw blind/buried vias
-    LAYER_VIA_THROUGH        = GAL_LAYER_ID_START +  3, ///< to draw usual through hole vias
-    LAYER_NON_PLATEDHOLES    = GAL_LAYER_ID_START +  4, ///< handle color for not plated holes (holes, not pads)
+     /// Meta control for all vias opacity/visibility.
+    LAYER_VIAS               = GAL_LAYER_ID_START +  0,
+    LAYER_VIA_MICROVIA       = GAL_LAYER_ID_START +  1, /// Draw micro vias.
+    LAYER_VIA_BBLIND         = GAL_LAYER_ID_START +  2, /// Draw blind/buried vias.
+    LAYER_VIA_THROUGH        = GAL_LAYER_ID_START +  3, /// Draw usual through hole vias.
+
+    /// Handle color for not plated holes (holes, not pads).
+    LAYER_NON_PLATEDHOLES    = GAL_LAYER_ID_START +  4,
     LAYER_FP_TEXT            = GAL_LAYER_ID_START +  5,
+
 //  LAYER_MOD_TEXT_BK deprecated                  +  6,
-//  LAYER_HIDDEN_TEXT        = GAL_LAYER_ID_START +  7, ///< DEPRECATED, UNUSED SINCE 9.0. text marked as invisible
-    LAYER_ANCHOR             = GAL_LAYER_ID_START +  8, ///< anchor of items having an anchor point (texts, footprints)
-//  LAYER_PADS_SMD_FR        = GAL_LAYER_ID_START +  9, ///< Deprecated since 9.0
-//  LAYER_PADS_SMD_BK        = GAL_LAYER_ID_START + 10, ///< Deprecated since 9.0
+
+//  DEPRECATED, UNUSED SINCE 9.0. text marked as invisible.
+//  LAYER_HIDDEN_TEXT        = GAL_LAYER_ID_START +  7,
+
+    /// Anchor of items having an anchor point (texts, footprints).
+    LAYER_ANCHOR             = GAL_LAYER_ID_START +  8,
+
+//  LAYER_PADS_SMD_FR        = GAL_LAYER_ID_START +  9, // Deprecated since 9.0
+//  LAYER_PADS_SMD_BK        = GAL_LAYER_ID_START + 10, // Deprecated since 9.0
+
     LAYER_RATSNEST           = GAL_LAYER_ID_START + 11,
     LAYER_GRID               = GAL_LAYER_ID_START + 12,
     LAYER_GRID_AXES          = GAL_LAYER_ID_START + 13,
-//  LAYER_NO_CONNECTS deprecated                  + 14, ///< show a marker on pads with no nets
-    LAYER_FOOTPRINTS_FR      = GAL_LAYER_ID_START + 15, ///< show footprints on front
-    LAYER_FOOTPRINTS_BK      = GAL_LAYER_ID_START + 16, ///< show footprints on back
-    LAYER_FP_VALUES          = GAL_LAYER_ID_START + 17, ///< show footprints values (when texts are visible)
-    LAYER_FP_REFERENCES      = GAL_LAYER_ID_START + 18, ///< show footprints references (when texts are visible)
+
+//  LAYER_NO_CONNECTS deprecated                  + 14, // show a marker on pads with no nets
+
+    LAYER_FOOTPRINTS_FR      = GAL_LAYER_ID_START + 15, ///< Show footprints on front.
+    LAYER_FOOTPRINTS_BK      = GAL_LAYER_ID_START + 16, ///< Show footprints on back.
+
+    /// Show footprints values (when texts are visible).
+    LAYER_FP_VALUES          = GAL_LAYER_ID_START + 17,
+
+    /// Show footprints references (when texts are visible).
+    LAYER_FP_REFERENCES      = GAL_LAYER_ID_START + 18,
     LAYER_TRACKS             = GAL_LAYER_ID_START + 19,
+
 //  LAYER_PADS_TH            = GAL_LAYER_ID_START + 20, ///< Deprecated since 9.0
+
     LAYER_PAD_PLATEDHOLES    = GAL_LAYER_ID_START + 21, ///< to draw pad holes (plated)
-    LAYER_VIA_HOLES          = GAL_LAYER_ID_START + 22, ///< to draw via holes (pad holes do not use this layer)
-    LAYER_DRC_ERROR          = GAL_LAYER_ID_START + 23, ///< layer for drc markers with SEVERITY_ERROR
-    LAYER_DRAWINGSHEET       = GAL_LAYER_ID_START + 24, ///< drawingsheet frame and titleblock
-    LAYER_GP_OVERLAY         = GAL_LAYER_ID_START + 25, ///< general purpose overlay
-    LAYER_SELECT_OVERLAY     = GAL_LAYER_ID_START + 26, ///< currently selected items overlay
-    LAYER_PCB_BACKGROUND     = GAL_LAYER_ID_START + 27, ///< PCB background color
-    LAYER_CURSOR             = GAL_LAYER_ID_START + 28, ///< PCB cursor
-    LAYER_AUX_ITEMS          = GAL_LAYER_ID_START + 29, ///< Auxiliary items (guides, rule, etc)
-    LAYER_DRAW_BITMAPS       = GAL_LAYER_ID_START + 30, ///< to handle and draw images bitmaps
+
+    /// Draw via holes (pad holes do not use this layer).
+    LAYER_VIA_HOLES          = GAL_LAYER_ID_START + 22,
+
+     /// Layer for DRC markers with #SEVERITY_ERROR.
+    LAYER_DRC_ERROR          = GAL_LAYER_ID_START + 23,
+    LAYER_DRAWINGSHEET       = GAL_LAYER_ID_START + 24, ///< Sheet frame and title block.
+    LAYER_GP_OVERLAY         = GAL_LAYER_ID_START + 25, ///< General purpose overlay.
+    LAYER_SELECT_OVERLAY     = GAL_LAYER_ID_START + 26, ///< Selected items overlay.
+    LAYER_PCB_BACKGROUND     = GAL_LAYER_ID_START + 27, ///< PCB background color.
+    LAYER_CURSOR             = GAL_LAYER_ID_START + 28, ///< PCB cursor.
+    LAYER_AUX_ITEMS          = GAL_LAYER_ID_START + 29, ///< Auxiliary items (guides, rule, etc).
+    LAYER_DRAW_BITMAPS       = GAL_LAYER_ID_START + 30, ///< Draw images.
 
     /// This is the end of the layers used for visibility bit masks in legacy board files
     GAL_LAYER_ID_BITMASK_END = GAL_LAYER_ID_START + 31,
 
     // Layers in this section have visibility controls but were not present in legacy board files.
 
-    LAYER_PADS               = GAL_LAYER_ID_START + 32, ///< Meta control for all pads opacity/visibility (color ignored)
-    LAYER_ZONES              = GAL_LAYER_ID_START + 33, ///< Control for copper zone opacity/visibility (color ignored)
+    /// Meta control for all pads opacity/visibility (color ignored).
+    LAYER_PADS               = GAL_LAYER_ID_START + 32,
+
+    /// Control for copper zone opacity/visibility (color ignored).
+    LAYER_ZONES              = GAL_LAYER_ID_START + 33,
 
     LAYER_PAD_HOLEWALLS      = GAL_LAYER_ID_START + 34,
     LAYER_VIA_HOLEWALLS      = GAL_LAYER_ID_START + 35,
-    LAYER_DRC_WARNING        = GAL_LAYER_ID_START + 36, ///< layer for drc markers with SEVERITY_WARNING
-    LAYER_DRC_EXCLUSION      = GAL_LAYER_ID_START + 37, ///< layer for drc markers which have been individually excluded
-    LAYER_MARKER_SHADOWS     = GAL_LAYER_ID_START + 38, ///< shadows for drc markers
 
-    LAYER_LOCKED_ITEM_SHADOW = GAL_LAYER_ID_START + 39, ///< shadow layer for locked items
+    /// Layer for DRC markers with #SEVERITY_WARNING.
+    LAYER_DRC_WARNING        = GAL_LAYER_ID_START + 36,
+
+    /// Layer for DRC markers which have been individually excluded.
+    LAYER_DRC_EXCLUSION      = GAL_LAYER_ID_START + 37,
+    LAYER_MARKER_SHADOWS     = GAL_LAYER_ID_START + 38, ///< Shadows for DRC markers.
+
+    LAYER_LOCKED_ITEM_SHADOW = GAL_LAYER_ID_START + 39, ///< Shadow layer for locked items.
+
+    /// Shadow layer for items flagged conflicting.
+    LAYER_CONFLICTS_SHADOW   = GAL_LAYER_ID_START + 40,
+
+    /// Copper graphic shape opacity/visibility (color ignored).
+    LAYER_SHAPES             = GAL_LAYER_ID_START + 41,
 
-    LAYER_CONFLICTS_SHADOW   = GAL_LAYER_ID_START + 40, ///< shadow layer for items flagged conficting
-    LAYER_SHAPES             = GAL_LAYER_ID_START + 41, ///< Copper graphic shape opacity/visibility (color ignored)
+    LAYER_DRC_SHAPE1         = GAL_LAYER_ID_START + 42,  ///< Custom shape for DRC marker.
+    LAYER_DRC_SHAPE2         = GAL_LAYER_ID_START + 43,  ///< Custom shape for DRC marker.
 
-    LAYER_DRC_SHAPE1         = GAL_LAYER_ID_START + 42,  ///< Custom shape for DRC marker
-    LAYER_DRC_SHAPE2         = GAL_LAYER_ID_START + 43,  ///< Custom shape for DRC marker
     // Add layers below this point that do not have visibility controls, so don't need explicit
     // enum values
 
-    LAYER_DRAWINGSHEET_PAGE1,      ///< for drawingsheetEditor previewing
-    LAYER_DRAWINGSHEET_PAGEn,      ///< for drawingsheetEditor previewing
+    LAYER_DRAWINGSHEET_PAGE1,      ///< Sheet Editor previewing first page.
+    LAYER_DRAWINGSHEET_PAGEn,      ///< Sheet Editor previewing pages after first page.
 
-    LAYER_PAGE_LIMITS,             ///< color for drawing the page extents (visibility stored in
-                                   ///<   PCBNEW_SETTINGS::m_ShowPageLimits)
+    LAYER_PAGE_LIMITS,             ///< Color for drawing the page extents (visibility stored in
+                                   ///< PCBNEW_SETTINGS::m_ShowPageLimits)
 
-    /// Virtual layers for stacking zones and tracks on a given copper layer
+    /// Virtual layers for stacking zones and tracks on a given copper layer.
     LAYER_ZONE_START,
     LAYER_ZONE_END = LAYER_ZONE_START + PCB_LAYER_ID_COUNT,
 
-    /// Virtual layers for pad copper on a given copper layer
+    /// Virtual layers for pad copper on a given copper layer.
     LAYER_PAD_COPPER_START,
     LAYER_PAD_COPPER_END = LAYER_PAD_COPPER_START + PCB_LAYER_ID_COUNT,
 
-    /// Virtual layers for via copper on a given copper layer
+    /// Virtual layers for via copper on a given copper layer.
     LAYER_VIA_COPPER_START,
     LAYER_VIA_COPPER_END = LAYER_VIA_COPPER_START + PCB_LAYER_ID_COUNT,
 
-    /// Virtual layers for pad/via/track clearance outlines for a given copper layer
+    /// Virtual layers for pad/via/track clearance outlines for a given copper layer.
     LAYER_CLEARANCE_START,
     LAYER_CLEARANCE_END = LAYER_CLEARANCE_START + PCB_LAYER_ID_COUNT,
 
-    /// Virtual layers for background images per board layer
+    /// Virtual layers for background images per board layer.
     LAYER_BITMAP_START,
     LAYER_BITMAP_END = LAYER_BITMAP_START + PCB_LAYER_ID_COUNT,
 
@@ -281,10 +313,10 @@ enum GAL_LAYER_ID: int
     GAL_LAYER_ID_END
 };
 
-/// Use this macro to convert a GAL layer to a 0-indexed offset from LAYER_VIAS
+/// Use this macro to convert a #GAL layer to a 0-indexed offset from #LAYER_VIAS.
 #define GAL_LAYER_INDEX( x ) ( x - GAL_LAYER_ID_START )
 
-/// Macros for getting the extra layers for a given board layer
+/// Macros for getting the extra layers for a given board layer.
 #define BITMAP_LAYER_FOR( boardLayer ) ( LAYER_BITMAP_START + boardLayer )
 #define ZONE_LAYER_FOR( boardLayer ) ( LAYER_ZONE_START + boardLayer )
 #define PAD_COPPER_LAYER_FOR( boardLayer ) ( LAYER_PAD_COPPER_START + boardLayer )
@@ -305,7 +337,7 @@ inline GAL_LAYER_ID ToGalLayer( int aInteger )
     return static_cast<GAL_LAYER_ID>( aInteger );
 }
 
-/// Used for via types
+/// Used for via types.
 inline GAL_LAYER_ID operator+( const GAL_LAYER_ID& a, int b )
 {
     GAL_LAYER_ID t = GAL_LAYER_ID( int( a ) + b );
@@ -314,11 +346,11 @@ inline GAL_LAYER_ID operator+( const GAL_LAYER_ID& a, int b )
 }
 
 
-/// @brief Wraps a std::bitset
+/// Wraps a std::bitset.
 typedef std::bitset<GAL_LAYER_ID_COUNT> GAL_BASE_SET;
 
 
-/// Helper for storing and iterating over GAL_LAYER_IDs
+/// Helper for storing and iterating over GAL_LAYER_IDs.
 class KICOMMON_API GAL_SET : public GAL_BASE_SET
 {
 
@@ -364,7 +396,7 @@ public:
     static GAL_SET DefaultVisible();
 };
 
-/// Eeschema drawing layers
+/// Eeschema drawing layers.
 enum SCH_LAYER_ID : int
 {
     SCH_LAYER_ID_START = GAL_LAYER_ID_END,
@@ -433,15 +465,15 @@ inline SCH_LAYER_ID operator++( SCH_LAYER_ID& a )
     return a;
 }
 
-// number of draw layers in Gerbview
+/// Number of draw layers in Gerbview.
 #define GERBER_DRAWLAYERS_COUNT static_cast<int>( PCB_LAYER_ID_COUNT )
 
-/// GerbView draw layers
+/// Gerbview draw layers.
 enum GERBVIEW_LAYER_ID: int
 {
     GERBVIEW_LAYER_ID_START = SCH_LAYER_ID_END,
 
-    /// GerbView draw layers and d-code layers
+    /// Gerbview draw layers and d-code layers
     GERBVIEW_LAYER_ID_RESERVED = GERBVIEW_LAYER_ID_START + ( 2 * GERBER_DRAWLAYERS_COUNT ),
 
     LAYER_DCODES,
@@ -494,13 +526,14 @@ enum LAYER_3D_ID : int
         LAYER_3D_END
 };
 
-/// Must update this if you add any enums after GerbView!
+/// Must update this if you add any enums after Gerbview!
 #define LAYER_ID_COUNT LAYER_3D_END
 
 
 /**
- * Returns the string equivalent of a given layer
- * @param aLayer is a valid layer ID
+ * Return the string equivalent of a given layer.
+ *
+ * @param aLayer is a valid layer ID.
  */
 KICOMMON_API wxString LayerName( int aLayer );
 
@@ -518,7 +551,7 @@ KICOMMON_API wxString LayerName( int aLayer );
 
 /**
  * Test whether a given integer is a valid layer index, i.e. can
- * be safely put in a PCB_LAYER_ID
+ * be safely put in a #PCB_LAYER_ID.
  *
  * @param aLayerId = Layer index to test. It can be an int, so its useful during I/O
  * @return true if aLayerIndex is a valid layer index
@@ -540,7 +573,7 @@ inline bool IsPcbLayer( int aLayer )
 }
 
 /**
- * Tests whether a layer is a copper layer.
+ * Test whether a layer is a copper layer.
  *
  * @param aLayerId = Layer  to test
  * @return true if aLayer is a valid copper layer
@@ -551,7 +584,7 @@ inline bool IsCopperLayer( int aLayerId )
 }
 
 /**
- * Tests whether a layer is an external (F_Cu or B_Cu) copper layer.
+ * Test whether a layer is an external (#F_Cu or #B_Cu) copper layer.
  *
  * @param aLayerId = Layer  to test
  * @return true if aLayer is a valid external copper layer
@@ -562,7 +595,7 @@ inline bool IsExternalCopperLayer( int aLayerId )
 }
 
 /**
- * Tests whether a layer is an inner (In1_Cu to In30_Cu) copper layer.
+ * Test whether a layer is an inner (#In1_Cu to #In30_Cu) copper layer.
  *
  * @param aLayerId = Layer  to test
  * @return true if aLayer is a valid inner copper layer
@@ -584,8 +617,8 @@ inline bool IsNonCopperLayer( int aLayerId )
 }
 
 /**
- * Tests whether a layer is a copper layer, optionally including synthetic copper layers such
- * as LAYER_VIA_THROUGH, LAYER_PADS_SMD_FR, etc.
+ * Test whether a layer is a copper layer, optionally including synthetic copper layers such
+ * as #LAYER_VIA_THROUGH, #LAYER_PADS_SMD_FR, etc.
  *
  * @param aLayerId
  * @param aIncludeSyntheticCopperLayers
@@ -644,7 +677,7 @@ inline bool IsUserLayer( PCB_LAYER_ID aLayerId )
  */
 
 /**
- * Layer classification: check if it's a front layer
+ * Layer classification: check if it's a front layer.
  */
 inline bool IsFrontLayer( PCB_LAYER_ID aLayerId )
 {
@@ -667,7 +700,7 @@ inline bool IsFrontLayer( PCB_LAYER_ID aLayerId )
 
 
 /**
- * Layer classification: check if it's a back layer
+ * Layer classification: check if it's a back layer.
  */
 inline bool IsBackLayer( PCB_LAYER_ID aLayerId )
 {
@@ -688,7 +721,7 @@ inline bool IsBackLayer( PCB_LAYER_ID aLayerId )
 
 
 /**
- * Returns true if copper aLayerA is placed lower than aLayerB, false otherwise.
+ * Return true if copper aLayerA is placed lower than aLayerB, false otherwise.
  */
 inline bool IsCopperLayerLowerThan( PCB_LAYER_ID aLayerA, PCB_LAYER_ID aLayerB )
 {
@@ -706,19 +739,19 @@ inline bool IsCopperLayerLowerThan( PCB_LAYER_ID aLayerA, PCB_LAYER_ID aLayerB )
 
 
 /**
+ * @param aLayerId = the PCB_LAYER_ID to flip
+ * @param aCopperLayersCount = the number of copper layers. if 0 (in fact if < 4 )
+ *  internal layers will be not flipped because the layer count is not known
  * @return the layer number after flipping an item
  * some (not all) layers: external copper, and paired layers( Mask, Paste, solder ... )
  * are swapped between front and back sides
  * internal layers are flipped only if the copper layers count is known
- * @param aLayerId = the PCB_LAYER_ID to flip
- * @param aCopperLayersCount = the number of copper layers. if 0 (in fact if < 4 )
- *  internal layers will be not flipped because the layer count is not known
  */
 KICOMMON_API PCB_LAYER_ID FlipLayer( PCB_LAYER_ID aLayerId, int aCopperLayersCount = 0 );
 
 
 /**
- * Returns a netname layer corresponding to the given layer.
+ * Return a netname layer corresponding to the given layer.
  */
 inline int GetNetnameLayer( int aLayer )
 {
@@ -772,7 +805,7 @@ inline bool IsDCodeLayer( int aLayer )
 }
 
 
-///! Converts KiCad copper layer enum to an ordinal between the front and back layers
+/// Converts KiCad copper layer enum to an ordinal between the front and back layers.
 inline size_t CopperLayerToOrdinal( PCB_LAYER_ID aLayer )
 {
     wxCHECK( IsCopperLayer( aLayer ), 0 );
@@ -787,7 +820,7 @@ inline size_t CopperLayerToOrdinal( PCB_LAYER_ID aLayer )
 
 
 /**
- * Retrieves a layer ID from an integer converted from a legacy (pre-V9) enum value
+ * Retrieve a layer ID from an integer converted from a legacy (pre-V9) enum value.
  */
 KICOMMON_API PCB_LAYER_ID BoardLayerFromLegacyId( int aLegacyId );
 

include/layer_range.h

@@ -43,7 +43,8 @@ private:
             if( m_reverse )
             {
                 if( aLayer == B_Cu )
-                    aLayer = m_layer_count == 2 ? F_Cu : static_cast<int>( F_Cu ) + 2 * ( m_layer_count - 2 ) + 2;
+                    aLayer = m_layer_count == 2 ? F_Cu :
+                             static_cast<int>( F_Cu ) + 2 * ( m_layer_count - 2 ) + 2;
                 else if( aLayer == m_stop || aLayer == UNDEFINED_LAYER )
                     aLayer = UNDEFINED_LAYER;
                 else if( aLayer == In1_Cu )
@@ -120,7 +121,9 @@ public:
                 throw std::invalid_argument( "Only works for copper layers" );
     }
 
-    LAYER_RANGE_ITERATOR begin() const { return LAYER_RANGE_ITERATOR( m_start, m_stop, m_layer_count ); }
+    LAYER_RANGE_ITERATOR begin() const { return LAYER_RANGE_ITERATOR( m_start, m_stop,
+                                                                      m_layer_count ); }
+
     LAYER_RANGE_ITERATOR end() const
     {
         auto it = LAYER_RANGE_ITERATOR( m_stop, m_stop, m_layer_count );
@@ -161,4 +164,4 @@ public:
     }
 };
 
-#endif // LAYER_RANGE_H
+#endif // LAYER_RANGE_H

include/lockfile.h

@@ -133,13 +133,14 @@ public:
     }
 
     /**
-     * Unlocks and removes the file from the filesystem as long as we still own it.
+     * Unlock and remove the file from the filesystem as long as we still own it.
      */
     void UnlockFile()
     {
         wxLogTrace( LCK, "Unlocking %s", m_lockFilename );
 
-        // Delete lock file only if the file was created in the constructor and if the file contains the correct user and host names
+        // Delete lock file only if the file was created in the constructor and if the file
+        // contains the correct user and host names.
         if( m_fileCreated && checkUserAndHost() )
         {
             if( m_removeOnRelease )
@@ -152,7 +153,8 @@ public:
     }
 
     /**
-     * Forces the lock, overwriting the data that existed already
+     * Force the lock, overwriting the data that existed already.
+     *
      * @return True if we successfully overrode the lock
      */
     bool OverrideLock( bool aRemoveOnRelease = true )
@@ -214,17 +216,19 @@ public:
     }
 
     /**
-     * @return Current username.  If we own the lock, this is us.  Otherwise, this is the user that does own it
+     * @return Current username.  If we own the lock, this is us.  Otherwise, this is the user
+     *         that does own it.
      */
     wxString GetUsername(){ return m_username; }
 
     /**
-     * @return Current hostname.  If we own the lock this is our computer.  Otherwise, this is the computer that does
+     * @return Current hostname.  If we own the lock this is our computer.  Otherwise, this is
+     *         the computer that does.
      */
     wxString GetHostname(){ return m_hostname; }
 
     /**
-     * @return Last error message generated
+     * @return Last error message generated.
      */
     wxString GetErrorMsg(){ return m_errorMsg; }
 
@@ -264,6 +268,7 @@ private:
         }
 
         wxFile file;
+
         try
         {
             if( file.Open( m_lockFilename, wxFile::read ) )

include/lset.h

@@ -27,10 +27,11 @@ class LSEQ;
 class LAYER_RANGE;
 
 /**
- * LSET is a set of PCB_LAYER_IDs.  It can be converted to numerous purpose LSEQs using
- * the various member functions, most of which are based on Seq(). The advantage
- * of converting to LSEQ using purposeful code, is it removes any dependency
- * on order/sequence inherent in this set.
+ * LSET is a set of PCB_LAYER_IDs.
+ *
+ * It can be converted to numerous purpose LSEQs using the various member functions, most of
+ * which are based on Seq(). The advantage of converting to #LSEQ using purposeful code, is it
+ * removes any dependency on order/sequence inherent in this set.
  */
 class KICOMMON_API LSET : public BASE_SET
 {
@@ -56,8 +57,8 @@ public:
     /**
      * See if the layer set contains a PCB layer.
      *
-     * @param aLayer is the layer to check
-     * @return true if the layer is included
+     * @param aLayer is the layer to check.
+     * @return true if the layer is included.
      */
     bool Contains( PCB_LAYER_ID aLayer ) const
     {
@@ -76,7 +77,7 @@ public:
     }
 
     /**
-     * Return the fixed name association with aLayerId.
+     * Return the fixed name association with @a aLayerId.
      */
     static wxString Name( PCB_LAYER_ID aLayerId );
 
@@ -86,24 +87,26 @@ public:
     static int NameToLayer( wxString& aName );
 
     /**
-     * Return true if aLayer is between aStart and aEnd, inclusive. Takes into
-     * account the direction of the layers and the fact that B_Cu comes before In*_Cu
+     * Return true if aLayer is between aStart and aEnd, inclusive.
+     *
+     * This takes into account the direction of the layers and the fact that #B_Cu comes before
+     * In*_Cu.
      */
     static bool IsBetween( PCB_LAYER_ID aStart, PCB_LAYER_ID aEnd, PCB_LAYER_ID aLayer );
 
     /**
      * Return a complete set of internal copper layers which is all Cu layers
-     * except F_Cu and B_Cu.
+     * except #F_Cu and #B_Cu.
      */
     static LSET InternalCuMask();
 
     /**
-     * Return a complete set of all top assembly layers which is all F_SilkS and F_Mask
+     * Return a complete set of all top assembly layers which is all #F_SilkS and #F_Mask.
      */
     static LSET FrontAssembly();
 
     /**
-     * Return a complete set of all bottom assembly layers which is all B_SilkS and B_Mask
+     * Return a complete set of all bottom assembly layers which is all #B_SilkS and #B_Mask.
      */
     static LSET BackAssembly();
 
@@ -171,8 +174,9 @@ public:
     static LSET UserMask();
 
     /**
-     * Return a mask holding all layers which are physically realized.  Equivalent to the copper
-     * layers + the board tech mask.
+     * Return a mask holding all layers which are physically realized.
+     *
+     * Equivalent to the copper layers + the board tech mask.
      */
     static LSET PhysicalLayersMask();
 
@@ -182,8 +186,9 @@ public:
     static LSET UserDefinedLayers();
 
     /**
-     * Layers which are not allowed within footprint definitions.  Currently internal
-     * copper layers and Margin.
+     * Layers which are not allowed within footprint definitions.
+     *
+     * Currently internal copper layers and Margin.
      */
 
     static LSET ForbiddenFootprintLayers();
@@ -195,30 +200,31 @@ public:
     LSEQ CuStack() const;
 
     /**
-     * Returns the technical and user layers in the order shown in layer widget
-     *
+     * Return the technical and user layers in the order shown in layer widget.
      */
     LSEQ TechAndUserUIOrder() const;
 
     /**
-     * Returns the copper, technical and user layers in the order shown in layer widget
-     *
+     * Return the copper, technical and user layers in the order shown in layer widget.
      */
     LSEQ UIOrder() const;
 
     /**
-     * Return an LSEQ from the union of this LSET and a desired sequence.  The LSEQ
-     * element will be in the same sequence as aWishListSequence if they are present.
+     * Return an #LSEQ from the union of this #LSET and a desired sequence.
+     *
+     * The #LSEQ element will be in the same sequence as aWishListSequence if they are present.
+     *
      * @param aWishListSequence establishes the order of the returned LSEQ, and the LSEQ will only
-     * contain PCB_LAYER_IDs which are present in this set.
+     *        contain PCB_LAYER_IDs which are present in this set.
      */
     LSEQ Seq( const LSEQ& aSequence ) const;
 
     /**
-     * Return a LSEQ from this LSET in ascending PCB_LAYER_ID order.  Each LSEQ
-     * element will be in the same sequence as in PCB_LAYER_ID and only present
-     * in the resultant LSEQ if present in this set.  Therefore the sequence is
-     * subject to change, use it only when enumeration and not order is important.
+     * Return a #LSEQ from this #LSET in ascending PCB_LAYER_ID order.
+     *
+     * Each #LSEQ element will be in the same sequence as in PCB_LAYER_ID and only present
+     * in the resultant #LSEQ if present in this set.  Therefore the sequence is subject to
+     * change, use it only when enumeration and not order is important.
      */
     LSEQ Seq() const;
 
@@ -226,19 +232,19 @@ public:
      * Generate a sequence of layers that represent a top to bottom stack of this set of layers.
      *
      * @param aSelectedLayer is the layer to put at the top of stack when defined.
-     *
      * @return the top to bottom layer sequence.
      */
     LSEQ SeqStackupTop2Bottom( PCB_LAYER_ID aSelectedLayer = UNDEFINED_LAYER ) const;
 
     /**
      * Return the sequence that is typical for a bottom-to-top stack-up.
+     *
      * For instance, to plot multiple layers in a single image, the top layers output last.
      */
     LSEQ SeqStackupForPlotting() const;
 
     /**
-     * Execute a function on each layer of the LSET.
+     * Execute a function on each layer of the #LSET.
      */
     void RunOnLayers( const std::function<void( PCB_LAYER_ID )>& aFunction ) const
     {
@@ -250,8 +256,9 @@ public:
     }
 
     /**
-     * Find the first set PCB_LAYER_ID. Returns UNDEFINED_LAYER if more
-     * than one is set or UNSELECTED_LAYER if none is set.
+     * Find the first set #PCB_LAYER_ID.
+     *
+     * @return #UNDEFINED_LAYER if more than one is set or #UNSELECTED_LAYER if none is set.
      */
     PCB_LAYER_ID ExtractLayer() const;
 
@@ -260,7 +267,8 @@ public:
      * Flip the layers in this set.
      *
      * BACK and FRONT copper layers, mask, paste, solder layers are swapped
-     * internal layers are flipped only if the copper layers count is known
+     * internal layers are flipped only if the copper layers count is known.
+     *
      * @param aMask = the LSET to flip
      * @param aCopperLayersCount = the number of copper layers. if 0 (in fact if < 4 )
      *  internal layers will be not flipped because the layer count is not known
@@ -282,7 +290,10 @@ public:
         {
         }
 
-        PCB_LAYER_ID operator*() const { return PCB_LAYER_ID( BASE_SET::set_bits_iterator::operator*() ); }
+        PCB_LAYER_ID operator*() const
+        {
+            return PCB_LAYER_ID( BASE_SET::set_bits_iterator::operator*() );
+        }
 
         all_set_layers_iterator& operator++()
         {
@@ -327,3 +338,4 @@ public:
 
 };
 #endif // LSET_H
+

include/macros_swig.h

@@ -39,18 +39,50 @@
 
 
 #ifdef SWIG
-/// Declare a std::vector and also the swig %template in unison
-#define DECL_VEC_FOR_SWIG(TypeName, MemberType) namespace std { %template(TypeName) vector<MemberType>; } typedef std::vector<MemberType> TypeName;
-#define DECL_DEQ_FOR_SWIG(TypeName, MemberType) namespace std { %template(TypeName) deque<MemberType>; } typedef std::deque<MemberType> TypeName;
-#define DECL_MAP_FOR_SWIG(TypeName, KeyType, ValueType) namespace std { %template(TypeName) map<KeyType, ValueType>; } typedef std::map<KeyType, ValueType> TypeName;
-#define DECL_SPTR_FOR_SWIG(TypeName, MemberType) %shared_ptr(MemberType) namespace std { %template(TypeName) shared_ptr<MemberType>; } typedef std::shared_ptr<MemberType> TypeName;
-#define DECL_SET_FOR_SWIG(TypeName, MemberType) namespace std { %template(TypeName) set<MemberType>; } typedef std::set<MemberType> TypeName;
+/// Declare a std::vector and also the swig %template in unison.
+#define DECL_VEC_FOR_SWIG( TypeName, MemberType )                       \
+    namespace std                                                       \
+    {                                                                   \
+    % template( TypeName ) vector<MemberType>;                          \
+    }                                                                   \
+    typedef std::vector<MemberType> TypeName;
+
+#define DECL_DEQ_FOR_SWIG( TypeName, MemberType )                       \
+    namespace std                                                       \
+    {                                                                   \
+    % template( TypeName ) deque<MemberType>;                           \
+    }                                                                   \
+    typedef std::deque<MemberType> TypeName;
+
+#define DECL_MAP_FOR_SWIG( TypeName, KeyType, ValueType )               \
+    namespace std                                                       \
+    {                                                                   \
+    % template( TypeName ) map<KeyType, ValueType>;                     \
+    }                                                                   \
+    typedef std::map<KeyType, ValueType> TypeName;
+
+#define DECL_SPTR_FOR_SWIG( TypeName, MemberType )                      \
+    % shared_ptr( MemberType ) namespace std                            \
+    {                                                                   \
+        % template( TypeName ) shared_ptr<MemberType>;                  \
+    }                                                                   \
+    typedef std::shared_ptr<MemberType> TypeName;
+
+#define DECL_SET_FOR_SWIG( TypeName, MemberType )                       \
+    namespace std                                                       \
+    {                                                                   \
+    % template( TypeName ) set<MemberType>;                             \
+    }                                                                   \
+    typedef std::set<MemberType> TypeName;
 #else
-/// Declare a std::vector but no swig %template
+/// Declare a std::vector but no swig %template,
 #define DECL_VEC_FOR_SWIG(TypeName, MemberType) typedef std::vector<MemberType> TypeName;
 #define DECL_DEQ_FOR_SWIG(TypeName, MemberType) typedef std::deque<MemberType> TypeName;
-#define DECL_MAP_FOR_SWIG(TypeName, KeyType, ValueType) typedef std::map<KeyType, ValueType> TypeName;
-#define DECL_SPTR_FOR_SWIG(TypeName, MemberType) typedef std::shared_ptr<MemberType> TypeName;
+
+#define DECL_MAP_FOR_SWIG( TypeName, KeyType, ValueType )               \
+    typedef std::map<KeyType, ValueType> TypeName;
+
+#define DECL_SPTR_FOR_SWIG( TypeName, MemberType ) typedef std::shared_ptr<MemberType> TypeName;
 #define DECL_SET_FOR_SWIG(TypeName, MemberType) typedef std::set<MemberType> TypeName;
 #endif
 

include/marker_base.h

@@ -42,8 +42,8 @@ namespace KIGFX
 using KIGFX::RENDER_SETTINGS;
 
 
-/*
- * Marker are mainly used to show a DRC or ERC error or warning
+/**
+ * Marker are mainly used to show a DRC or ERC error or warning.
  */
 class MARKER_BASE
 {
@@ -112,16 +112,16 @@ public:
     std::shared_ptr<RC_ITEM> GetRCItem() const { return m_rcItem; }
 
     /**
-     * Test if the given VECTOR2I is within the bounds of this object.
+     * Test if the given #VECTOR2I is within the bounds of this object.
      *
-     * @param aHitPosition is the VECTOR2I to test (in internal units).
+     * @param aHitPosition is the #VECTOR2I to test (in internal units).
      * @return true if a hit, else false.
      */
     bool HitTestMarker( const VECTOR2I& aHitPosition, int aAccuracy ) const;
 
     /**
-    * Test if the given BOX2I intersects or contains the bounds of this object
-*/
+     * Test if the given #BOX2I intersects or contains the bounds of this object.
+     */
     bool HitTestMarker( const BOX2I& aRect, bool aContained, int aAccuracy = 0 ) const;
 
     /**
@@ -137,19 +137,19 @@ protected:
     virtual KIGFX::COLOR4D getColor() const = 0;
 
 public:
-    VECTOR2I            m_Pos;                 ///< position of the marker
+    VECTOR2I            m_Pos;                 ///< Position of the marker.
 
 protected:
-    MARKER_T            m_markerType;          // The type of marker (useful to filter markers)
-    bool                m_excluded;            // User has excluded this specific error
-    wxString            m_comment;             // User-supplied comment (generally for exclusions)
+    MARKER_T            m_markerType;          ///< The type of marker.
+    bool                m_excluded;            ///< User has excluded this specific error.
+    wxString            m_comment;             ///< User supplied comment.
     std::shared_ptr<RC_ITEM> m_rcItem;
 
-    int                 m_scalingFactor;       // Scaling factor to convert corners coordinates
-                                               // to internal units coordinates
-    BOX2I               m_shapeBoundingBox;    // Bounding box of the graphic symbol, relative
-                                               // to the position of the shape, in marker shape
-                                               // units
+    int                 m_scalingFactor;       ///< Scaling factor to convert corners coordinates
+                                               ///< to internal units coordinates.
+    BOX2I               m_shapeBoundingBox;    ///< Bounding box of the graphic symbol relative
+                                               ///< to the position of the shape in marker shape
+                                               ///< units.
 };
 
 

include/plugins/3dapi/ifsg_index.h

@@ -52,7 +52,7 @@ public:
      * Set the number of indices and creates a copy of the given index data.
      *
      * @param nIndices is the number of indices to be stored.
-     * @param aIndexList [in] is the index data.
+     * @param[in] aIndexList is the index data.
      */
     bool SetIndices( size_t nIndices, int* aIndexList );
 

include/plugins/3dapi/ifsg_node.h

@@ -93,7 +93,7 @@ public:
     /**
      * Set the parent SGNODE of this object.
      *
-     * @param aParent [in] is the desired parent node.
+     * @param[in] aParent is the desired parent node.
      * @return true if the operation succeeds; false if the given node is not allowed to be a
      *              parent to the derived object.
      */