diff --git a/include/advanced_config.h b/include/advanced_config.h
index a3c16c326a..f9c4134950 100644
--- a/include/advanced_config.h
+++ b/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 );
};
diff --git a/include/array_axis.h b/include/array_axis.h
index 8b05e4522f..493415a391 100644
--- a/include/array_axis.h
+++ b/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
\ No newline at end of file
+#endif // ARRAY_AXIS__H
diff --git a/include/array_options.h b/include/array_options.h
index 85e672e6a3..e45deefff9 100644
--- a/include/array_options.h
+++ b/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;
diff --git a/include/base_set.h b/include/base_set.h
index 6c4c819eec..b4480ef2c2 100644
--- a/include/base_set.h
+++ b/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 )
{
diff --git a/include/base_units.h b/include/base_units.h
index 154544db20..da59375acd 100644
--- a/include/base_units.h
+++ b/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
{
diff --git a/include/bitmap_base.h b/include/bitmap_base.h
index 302fbdd0f8..366e4f22a4 100644
--- a/include/bitmap_base.h
+++ b/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.)
+ 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
+ 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
diff --git a/include/board_design_settings.h b/include/board_design_settings.h
index f497338e7b..35218a95dc 100644
--- a/include/board_design_settings.h
+++ b/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;
};
diff --git a/include/board_item.h b/include/board_item.h
index a3d921849b..8bb0b0f629 100644
--- a/include/board_item.h
+++ b/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,
diff --git a/include/board_printout.h b/include/board_printout.h
index e3ffd341cb..0d3eca7502 100644
--- a/include/board_printout.h
+++ b/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;
};
diff --git a/include/commit.h b/include/commit.h
index 6dc8e86ee4..74bd0afffa 100644
--- a/include/commit.h
+++ b/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();
diff --git a/include/ctl_flags.h b/include/ctl_flags.h
index 49217c3ebe..d9fb82a861 100644
--- a/include/ctl_flags.h
+++ b/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.
diff --git a/include/design_block_lib_table.h b/include/design_block_lib_table.h
index f35f947236..ca05520228 100644
--- a/include/design_block_lib_table.h
+++ b/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.
*/
diff --git a/include/dpi_scaling.h b/include/dpi_scaling.h
index 79c15c574e..0b9b85edc2 100644
--- a/include/dpi_scaling.h
+++ b/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
\ No newline at end of file
+#endif // DPI_SCALING__H
diff --git a/include/dsnlexer.h b/include/dsnlexer.h
index c9efcfb4e8..01fa01c030 100644
--- a/include/dsnlexer.h
+++ b/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
};
diff --git a/include/eda_base_frame.h b/include/eda_base_frame.h
index 5805f7968e..0ac1805c8e 100644
--- a/include/eda_base_frame.h
+++ b/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;
};
diff --git a/include/eda_dde.h b/include/eda_dde.h
index 644e03e91c..3b8ca1dea0 100644
--- a/include/eda_dde.h
+++ b/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_
diff --git a/include/eda_draw_frame.h b/include/eda_draw_frame.h
index 01a4ca7915..56ea739f52 100644
--- a/include/eda_draw_frame.h
+++ b/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;
diff --git a/include/eda_item.h b/include/eda_item.h
index ec7c9e9b66..d61d8eb4d8 100644
--- a/include/eda_item.h
+++ b/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;
};
diff --git a/include/eda_pattern_match.h b/include/eda_pattern_match.h
index 0d1bf09221..ca3986585f 100644
--- a/include/eda_pattern_match.h
+++ b/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;
diff --git a/include/eda_shape.h b/include/eda_shape.h
index bfe8ce8ca6..4b6cca3bd7 100644
--- a/include/eda_shape.h
+++ b/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.
*
- * @param aStart Cached start point
- * @param aMid Cached mid point
- * @param aEnd Cached end point
- * @param aCenter Calculated center point using the preceeding three
+ * 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.
*/
- 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;
diff --git a/include/eda_tools.h b/include/eda_tools.h
index 98bdb1abcd..05d8bb37ba 100644
--- a/include/eda_tools.h
+++ b/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 );
diff --git a/include/eda_units.h b/include/eda_units.h
index 01c08a35cb..ad435335bc 100644
--- a/include/eda_units.h
+++ b/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,
diff --git a/include/embedded_files.h b/include/embedded_files.h
index 13422ea7b9..37c79de1c2 100644
--- a/include/embedded_files.h
+++ b/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.
};
diff --git a/include/enum_vector.h b/include/enum_vector.h
index e8fc02ffce..adbfd73be6 100644
--- a/include/enum_vector.h
+++ b/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]
diff --git a/include/env_paths.h b/include/env_paths.h
index 57bfa68377..6879c9241e 100644
--- a/include/env_paths.h
+++ b/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 );
diff --git a/include/env_vars.h b/include/env_vars.h
index 4d5cfbc92f..68e4a6fc88 100644
--- a/include/env_vars.h
+++ b/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,
diff --git a/include/filename_resolver.h b/include/filename_resolver.h
index 71b576ee68..ca687f567e 100644
--- a/include/filename_resolver.h
+++ b/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;
diff --git a/include/filter_reader.h b/include/filter_reader.h
index 2d34780bb0..993e68cb25 100644
--- a/include/filter_reader.h
+++ b/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 );
diff --git a/include/gal_display_options_common.h b/include/gal_display_options_common.h
index 58f73887ab..ba4fb5206c 100644
--- a/include/gal_display_options_common.h
+++ b/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 );
diff --git a/include/gbr_metadata.h b/include/gbr_metadata.h
index 086bb1a78c..189e07f43f 100644
--- a/include/gbr_metadata.h
+++ b/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
};
diff --git a/include/gestfich.h b/include/gestfich.h
index ca5083130f..549c1c1da1 100644
--- a/include/gestfich.h
+++ b/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 );
diff --git a/include/hash_eda.h b/include/hash_eda.h
index fa3c607b05..4c02eba9a7 100644
--- a/include/hash_eda.h
+++ b/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,
diff --git a/include/hotkeys_basic.h b/include/hotkeys_basic.h
index 68fb21af5f..2b1df9965a 100644
--- a/include/hotkeys_basic.h
+++ b/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.
*/
diff --git a/include/id.h b/include/id.h
index de67b4a15b..4bcffc9430 100644
--- a/include/id.h
+++ b/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,
diff --git a/include/ki_any.h b/include/ki_any.h
index 1d22c3cbcf..4613a1c4b3 100644
--- a/include/ki_any.h
+++ b/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
{
diff --git a/include/kidialog.h b/include/kidialog.h
index 86fcea1bf7..2987ae0076 100644
--- a/include/kidialog.h
+++ b/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();
diff --git a/include/kiway_player.h b/include/kiway_player.h
index 1926d819d0..4b6d709dc5 100644
--- a/include/kiway_player.h
+++ b/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()
diff --git a/include/layer_ids.h b/include/layer_ids.h
index 248dd3de0f..a346265f9d 100644
--- a/include/layer_ids.h
+++ b/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_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 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_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 );
diff --git a/include/layer_range.h b/include/layer_range.h
index f09b797257..f715db7ff6 100644
--- a/include/layer_range.h
+++ b/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
\ No newline at end of file
+#endif // LAYER_RANGE_H
diff --git a/include/lockfile.h b/include/lockfile.h
index 7d8a9c63ad..4911048029 100644
--- a/include/lockfile.h
+++ b/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 ) )
diff --git a/include/lset.h b/include/lset.h
index c915d41113..7dd0e37621 100644
--- a/include/lset.h
+++ b/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
+
diff --git a/include/marker_base.h b/include/marker_base.h
index df54187f48..869ff2053c 100644
--- a/include/marker_base.h
+++ b/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.
};
diff --git a/include/plugins/3dapi/ifsg_index.h b/include/plugins/3dapi/ifsg_index.h
index 80fe115a7f..17839cb8b7 100644
--- a/include/plugins/3dapi/ifsg_index.h
+++ b/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 );
diff --git a/include/plugins/3dapi/ifsg_node.h b/include/plugins/3dapi/ifsg_node.h
index dda5232335..1d2eb80cc5 100644
--- a/include/plugins/3dapi/ifsg_node.h
+++ b/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.
*/