From 6ab1144ea3846846b4752193a288b35f44750601 Mon Sep 17 00:00:00 2001 From: Wayne Stambaugh Date: Mon, 25 Jan 2021 07:42:36 -0500 Subject: [PATCH] Fix broken Doxygen comment specifiers. Please note, ///> is not a valid Doxygen comment specifier. ///< is the correct specifier to use for single line or short Doxygen comments. --- 3d-viewer/3d_viewer/tools/3d_actions.h | 4 +- 3d-viewer/3d_viewer/tools/3d_conditions.h | 10 +- 3d-viewer/3d_viewer/tools/3d_controller.h | 4 +- bitmap2component/bitmap2cmp_gui.h | 4 +- common/dialog_about/aboutinfo.h | 6 +- common/dialogs/wx_html_report_box.h | 8 +- common/dialogs/wx_html_report_panel.h | 56 +- common/plugins/eagle/eagle_parser.h | 87 ++- common/preview_items/arc_geom_manager.cpp | 4 +- common/preview_items/ruler_item.cpp | 8 +- common/tool/tool_dispatcher.cpp | 38 +- common/tool/tool_manager.cpp | 13 +- common/view/view.cpp | 41 +- include/board_printout.h | 20 +- include/commit.h | 39 +- include/common.h | 4 +- include/confirm.h | 17 +- include/cursors.h | 14 +- include/dialogs/dialog_color_picker.h | 30 +- include/env_paths.h | 26 +- include/gal/cairo/cairo_gal.h | 18 +- include/gal/cairo/cairo_print.h | 12 +- include/gal/gal_display_options.h | 20 +- include/gal/graphics_abstraction_layer.h | 75 ++- include/gal/opengl/cached_container.h | 28 +- include/gal/opengl/cached_container_gpu.h | 13 +- include/gal/opengl/cached_container_ram.h | 8 +- include/gal/opengl/gpu_manager.h | 48 +- include/gal/opengl/opengl_gal.h | 82 +-- include/gal/opengl/vertex_common.h | 7 +- include/gal/opengl/vertex_container.h | 10 +- include/gal/stroke_font.h | 19 +- include/gl_context_mgr.h | 9 +- include/hash_eda.h | 16 +- include/intrusive_list.h | 4 +- include/multivector.h | 23 +- include/origin_viewitem.h | 17 +- include/pcb_group.h | 52 +- include/preview_items/arc_geom_manager.h | 46 +- include/preview_items/centreline_rect_item.h | 23 +- .../preview_items/multistep_geom_manager.h | 54 +- include/preview_items/polygon_geom_manager.h | 44 +- include/preview_items/polygon_item.h | 18 +- include/preview_items/ruler_item.h | 10 +- include/preview_items/selection_area.h | 12 +- include/preview_items/simple_overlay_item.h | 18 +- .../preview_items/two_point_geom_manager.h | 23 +- include/project.h | 16 +- include/project/board_project_settings.h | 18 +- include/property.h | 39 +- include/property_mgr.h | 56 +- include/status_popup.h | 6 +- include/validators.h | 10 +- include/widgets/bitmap_button.h | 12 +- include/widgets/bitmap_toggle.h | 12 +- include/widgets/gal_options_panel.h | 5 +- include/widgets/indicator_icon.h | 34 +- include/widgets/lib_tree.h | 22 +- include/widgets/text_ctrl_eval.h | 14 +- include/widgets/unit_binder.h | 56 +- include/widgets/wx_busy_indicator.h | 6 +- libs/kimath/include/bezier_curves.h | 10 +- libs/kimath/include/geometry/direction45.h | 65 +-- libs/kimath/include/geometry/seg.h | 77 ++- libs/kimath/include/geometry/shape.h | 101 ++-- libs/kimath/include/geometry/shape_poly_set.h | 513 +++++++++--------- libs/kimath/include/geometry/shape_rect.h | 40 +- libs/kimath/include/math/vector2d.h | 69 ++- libs/kimath/include/math/vector3.h | 34 +- 69 files changed, 1128 insertions(+), 1229 deletions(-) diff --git a/3d-viewer/3d_viewer/tools/3d_actions.h b/3d-viewer/3d_viewer/tools/3d_actions.h index a06351b6ef..699dcc8f45 100644 --- a/3d-viewer/3d_viewer/tools/3d_actions.h +++ b/3d-viewer/3d_viewer/tools/3d_actions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -99,7 +99,7 @@ public: static TOOL_ACTION toggleComments; static TOOL_ACTION toggleECO; - ///> @copydoc COMMON_ACTIONS::TranslateLegacyId() + ///< @copydoc COMMON_ACTIONS::TranslateLegacyId() virtual OPT TranslateLegacyId( int aId ) override { return OPT(); } }; diff --git a/3d-viewer/3d_viewer/tools/3d_conditions.h b/3d-viewer/3d_viewer/tools/3d_conditions.h index 0633714624..4152f6661c 100644 --- a/3d-viewer/3d_viewer/tools/3d_conditions.h +++ b/3d-viewer/3d_viewer/tools/3d_conditions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 Ian McInerney - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -72,19 +72,19 @@ public: SELECTION_CONDITION GridSize( GRID3D_TYPE aGridSize ); private: - ///> Helper function used by MaterialMode() + ///< Helper function used by MaterialMode() static bool materialModeFunction( const SELECTION& aSelection, BOARD_ADAPTER* aAdapter, MATERIAL_MODE aMaterial ); - ///> Helper function used by Flag() + ///< Helper function used by Flag() static bool flagFunction( const SELECTION& aSelection, BOARD_ADAPTER* aAdapter, DISPLAY3D_FLG aFlag ); - ///> Helper function used by GridDize() + ///< Helper function used by GridDize() static bool gridSizeFunction( const SELECTION& aSelection, BOARD_ADAPTER* aAdapter, GRID3D_TYPE aGridSize ); - ///> The board adapter to read the 3D viewer state from + ///< The board adapter to read the 3D viewer state from BOARD_ADAPTER* m_adapter; }; diff --git a/3d-viewer/3d_viewer/tools/3d_controller.h b/3d-viewer/3d_viewer/tools/3d_controller.h index c36e930d12..c0f4ead004 100644 --- a/3d-viewer/3d_viewer/tools/3d_controller.h +++ b/3d-viewer/3d_viewer/tools/3d_controller.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -97,7 +97,7 @@ public: int ToggleVisibility( const TOOL_EVENT& aEvent ); private: - ///> Sets up handlers for various events. + ///< Sets up handlers for various events. void setTransitions() override; int doZoomInOut( bool aDirection, bool aCenterOnCursor ); diff --git a/bitmap2component/bitmap2cmp_gui.h b/bitmap2component/bitmap2cmp_gui.h index fca3ee70f1..c981717f8f 100644 --- a/bitmap2component/bitmap2cmp_gui.h +++ b/bitmap2component/bitmap2cmp_gui.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KICAD, a free EDA CAD application. * - * Copyright (C) 2019 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -100,7 +100,7 @@ private: void OnExportToFile( wxCommandEvent& event ) override; void OnExportToClipboard( wxCommandEvent& event ) override; - ///> @return the EDA_UNITS from the m_PixelUnit choice + ///< @return the EDA_UNITS from the m_PixelUnit choice EDA_UNITS getUnitFromSelection(); // return a string giving the output size, according to the selected unit diff --git a/common/dialog_about/aboutinfo.h b/common/dialog_about/aboutinfo.h index 5dfae3bacd..e34fab1ad1 100644 --- a/common/dialog_about/aboutinfo.h +++ b/common/dialog_about/aboutinfo.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 Rafael Sokolowski - * Copyright (C) 2014-2017 KiCad Developers, see CHANGELOG.TXT for contributors. + * Copyright (C) 2014-2021 KiCad Developers, see CHANGELOG.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -114,7 +114,7 @@ public: void SetAppIcon( const wxIcon& aIcon ) { m_appIcon = aIcon; } wxIcon& GetAppIcon() { return m_appIcon; } - ///> Wrapper to manage memory allocation for bitmaps + ///< Wrapper to manage memory allocation for bitmaps wxBitmap* CreateKiBitmap( BITMAP_DEF aBitmap ) { m_bitmaps.emplace_back( KiBitmapNew( aBitmap ) ); @@ -140,7 +140,7 @@ private: wxIcon m_appIcon; - ///> Bitmaps to be freed when the dialog is closed + ///< Bitmaps to be freed when the dialog is closed std::vector> m_bitmaps; }; diff --git a/common/dialogs/wx_html_report_box.h b/common/dialogs/wx_html_report_box.h index 996275c5c0..9ba84f9e33 100644 --- a/common/dialogs/wx_html_report_box.h +++ b/common/dialogs/wx_html_report_box.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see change_log.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -27,9 +27,7 @@ #include /** - * WX_HTML_REPORT_BOX - * - * A slimmed down version of WX_HTML_REPORT_PANEL + * A slimmed down version of #WX_HTML_REPORT_PANEL */ class WX_HTML_REPORT_BOX : public wxHtmlWindow, public REPORTER { @@ -60,7 +58,7 @@ private: // reports, but can be very slow for larger reports. bool m_immediateMode; - ///> copy of the report, stored for filtering + ///< copy of the report, stored for filtering std::vector m_messages; }; diff --git a/common/dialogs/wx_html_report_panel.h b/common/dialogs/wx_html_report_panel.h index 325132c597..4ef34fa907 100644 --- a/common/dialogs/wx_html_report_panel.h +++ b/common/dialogs/wx_html_report_panel.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015 CERN - * Copyright (C) 2015 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2015-2021 KiCad Developers, see change_log.txt for contributors. * Author: Tomasz Wlostowski * * This program is free software: you can redistribute it and/or modify it @@ -30,8 +30,6 @@ /** - * WX_HTML_REPORT_PANEL - * * A widget for browsing a rich text error/status report. Used in numerous * dialogs in eeschema and pcbnew. Provides error filtering functionality * and saving report files. @@ -46,10 +44,10 @@ public: const wxSize& size = wxSize( 500,300 ), long style = wxTAB_TRAVERSAL ); ~WX_HTML_REPORT_PANEL(); - ///> Set the min size of the area which displays html messages: + ///< Set the min size of the area which displays html messages: void MsgPanelSetMinSize( const wxSize& aMinSize ); - ///> returns the reporter object that reports to this panel + ///< returns the reporter object that reports to this panel REPORTER& Reporter(); /** @@ -61,43 +59,43 @@ public: void Report( const wxString& aText, SEVERITY aSeverity, REPORTER::LOCATION aLocation = REPORTER::LOC_BODY ); - ///> clears the report panel + ///< clears the report panel void Clear(); - ///> return the number of messages matching the given severity mask. + ///< return the number of messages matching the given severity mask. int Count( int severityMask ); - ///> sets the frame label + ///< sets the frame label void SetLabel( const wxString& aLabel ) override; - ///> Sets the lasy update. If this mode is on, messages are stored but the display - ///> is not updated (Updating display can be very time consumming if there are many messages) - ///> A call to Flush() will be needed after build the report + ///< Sets the lasy update. If this mode is on, messages are stored but the display + ///< is not updated (Updating display can be very time consumming if there are many messages) + ///< A call to Flush() will be needed after build the report void SetLazyUpdate( bool aLazyUpdate ); - ///> Forces updating the HTML page, after the report is built in lazy mode - ///> If aSort = true, the body messages will be ordered by severity + ///< Forces updating the HTML page, after the report is built in lazy mode + ///< If aSort = true, the body messages will be ordered by severity void Flush( bool aSort = false ); - ///> Set the visible severity filter. - ///> if aSeverities < 0 the m_showAll option is set + ///< Set the visible severity filter. + ///< if aSeverities < 0 the m_showAll option is set void SetVisibleSeverities( int aSeverities ); - ///> @return the visible severity filter. - ///> If the m_showAll option is set, the mask is < 0 + ///< @return the visible severity filter. + ///< If the m_showAll option is set, the mask is < 0 int GetVisibleSeverities() const; - ///> If true prints Info: at the beginning of each Info severity line (Default) + ///< If true prints Info: at the beginning of each Info severity line (Default) void SetPrintInfo( bool aPrintInfo ); - ///> @return the visible severity filter. - ///> If the m_showAll option is set, the mask is < 0 + ///< @return the visible severity filter. + ///< If the m_showAll option is set, the mask is < 0 void SetShowSeverity( SEVERITY aSeverity, bool aValue ); - ///> Set the report full file name to the string + ///< Set the report full file name to the string void SetFileName( const wxString& aReportFileName ); - ///> @return reference to the current report fill file name string. + ///< @return reference to the current report fill file name string. wxString& GetFileName( void ); @@ -128,27 +126,27 @@ private: void onBtnSaveToFile( wxCommandEvent& event ) override; - ///> copy of the report, stored for filtering + ///< copy of the report, stored for filtering REPORT_LINES m_report; - ///> Lines to print at the very end of the report, regardless of sorting + ///< Lines to print at the very end of the report, regardless of sorting REPORT_LINES m_reportTail; - ///> Lines to print at the very beginning of the report, regardless of sorting + ///< Lines to print at the very beginning of the report, regardless of sorting REPORT_LINES m_reportHead; - ///> the reporter + ///< the reporter WX_HTML_PANEL_REPORTER m_reporter; - ///> message severities to display (mask) + ///< message severities to display (mask) int m_severities; bool m_lazyUpdate; - ///> Print "Info:" at the front of Info messages (default) + ///< Print "Info:" at the front of Info messages (default) bool m_printInfo; - ///> Use this as the filename instead of /bin/report.txt (default) + ///< Use this as the filename instead of /bin/report.txt (default) wxString m_reportFileName; }; diff --git a/common/plugins/eagle/eagle_parser.h b/common/plugins/eagle/eagle_parser.h index f598ce88d8..673ca4589f 100644 --- a/common/plugins/eagle/eagle_parser.h +++ b/common/plugins/eagle/eagle_parser.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2012-2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2017 CERN * @author Alejandro García Montoro * @@ -52,7 +52,7 @@ typedef std::map FOOTPRINT_MAP; typedef std::map EINSTANCE_MAP; typedef std::map> EPART_MAP; -///> Translates Eagle special characters to their counterparts in KiCad. +///< Translates Eagle special characters to their counterparts in KiCad. wxString escapeName( const wxString& aNetName ); static inline wxXmlNode* getChildrenNodes( NODE_MAP& aMap, const wxString& aName ) @@ -63,8 +63,7 @@ static inline wxXmlNode* getChildrenNodes( NODE_MAP& aMap, const wxString& aName /** - * XML_PARSER_ERROR - * implements a simple wrapper around runtime_error to isolate the errors thrown by the + * Implement a simple wrapper around runtime_error to isolate the errors thrown by the * Eagle XML parser. */ struct XML_PARSER_ERROR : std::runtime_error @@ -97,8 +96,8 @@ struct TRIPLET /** - * XPATH - * keeps track of what we are working on within a PTREE. + * Keep track of what we are working on within a PTREE. + * * Then if an exception is thrown, the place within the tree that gave us * grief can be reported almost accurately. To minimally impact * speed, merely assign const char* pointers during the tree walking @@ -165,8 +164,8 @@ public: /** - * Function Convert - * converts a wxString to a generic type T. + * Convert a wxString to a generic type T. + * * @param aValue is a wxString containing the value that will be converted to type T. * @throw XML_PARSER_ERROR - an exception is thrown if the parsing fails or if the conversion to * type T is unknown. @@ -181,8 +180,8 @@ template <> wxString Convert( const wxString& aValue ); /** - * OPTIONAL_XML_ATTRIBUTE - * models an optional XML attribute. + * Model an optional XML attribute. + * * This was implemented as an alternative to OPT. This class should be replaced with a * simple typedef per type using std::optional when C++17 is published. */ @@ -198,8 +197,7 @@ private: public: /** - * Constructor OPTIONAL_XML_ATTRIBUTE - * construct a default OPTIONAL_XML_ATTRIBUTE, whose data is not available. + * Construct a default OPTIONAL_XML_ATTRIBUTE, whose data is not available. */ OPTIONAL_XML_ATTRIBUTE() : m_isAvailable( false ), @@ -207,7 +205,6 @@ public: {} /** - * Constructor OPTIONAL_XML_ATTRIBUTE * @param aData is a wxString containing the value that should be converted to type T. If * aData is empty, the attribute is understood as unavailable; otherwise, the * conversion to T is tried. @@ -222,7 +219,6 @@ public: } /** - * Constructor OPTIONAL_XML_ATTRIBUTE * @param aData is the value of the XML attribute. If this constructor is called, the * attribute is available. */ @@ -233,8 +229,7 @@ public: {} /** - * Operator bool - * @return bool - the availability of the attribute. + * @return bool the availability of the attribute. */ operator bool() const { @@ -242,8 +237,8 @@ public: } /** - * Assignment operator - * to a string (optionally) containing the data. + * Assign to a string (optionally) containing the data. + * * @param aData is a wxString that should be converted to T. If the string is empty, the * attribute is set to unavailable. */ @@ -258,8 +253,8 @@ public: } /** - * Assignment operator - * to an object of the base type containing the data. + * Assign to an object of the base type containing the data. + * * @param aData is the actual value of the attribute. Calling this assignment, the attribute * is automatically made available. */ @@ -272,8 +267,6 @@ public: } /** - * Equal operator - * to an object of the base type. * @param aOther is the object of the base type that should be compared with this one. */ bool operator ==( const T& aOther ) const @@ -282,8 +275,8 @@ public: } /** - * Function Set - * tries to convert a string to the base type. + * Attempt to convert a string to the base type. + * * @param aString is the string that will be converted to the base type. */ void Set( const wxString& aString ) @@ -293,8 +286,8 @@ public: } /** - * Function Get - * returns a reference to the value of the attribute assuming it is available. + * Return a reference to the value of the attribute assuming it is available. + * * @return T& - the value of the attribute. */ T& Get() @@ -304,8 +297,8 @@ public: } /** - * Function CGet - * returns a constant reference to the value of the attribute assuming it is available. + * Return a constant reference to the value of the attribute assuming it is available. + * * @return const T& - the value of the attribute. */ const T& CGet() const @@ -315,8 +308,8 @@ public: } /** - * Operator * - * returns a reference to the value of the attribute assuming it is available. + * Return a reference to the value of the attribute assuming it is available. + * * @return T& - the value of the attribute. */ T& operator*() @@ -325,8 +318,8 @@ public: } /** - * Operator * - * returns a constant reference to the value of the attribute assuming it is available. + * Return a constant reference to the value of the attribute assuming it is available. + * * @return const T& - the value of the attribute. */ const T& operator*() const @@ -335,8 +328,8 @@ public: } /** - * Operator -> - * returns a pointer to the value of the attribute assuming it is available. + * Return a pointer to the value of the attribute assuming it is available. + * * @return T* - the value of the attribute. */ T* operator->() @@ -345,8 +338,8 @@ public: } /** - * Operator -> - * returns a constant pointer to the value of the attribute assuming it is available. + * Return a constant pointer to the value of the attribute assuming it is available. + * * @return const T* - the value of the attribute. */ const T* operator->() const @@ -357,15 +350,15 @@ public: /** - * Function MapChildren - * provides an easy access to the children of an XML node via their names. + * Provide an easy access to the children of an XML node via their names. + * * @param currentNode is a pointer to a wxXmlNode, whose children will be mapped. - * @return NODE_MAP - a map linking the name of each children to the children itself (via a + * @return NODE_MAP is a map linking the name of each children to the children itself (via a * wxXmlNode*) */ NODE_MAP MapChildren( wxXmlNode* aCurrentNode ); -///> Convert an Eagle curve end to a KiCad center for S_ARC +///< Convert an Eagle curve end to a KiCad center for S_ARC wxPoint ConvertArcCenter( const wxPoint& aStart, const wxPoint& aEnd, double aAngle ); // Pre-declare for typedefs @@ -396,10 +389,10 @@ struct ECOORD EU_MIL, ///< mils/thous }; - ///> Value expressed in nanometers + ///< Value expressed in nanometers long long int value; - ///> Unit used for the value field + ///< Unit used for the value field static constexpr EAGLE_UNIT ECOORD_UNIT = EU_NM; ECOORD() @@ -452,7 +445,7 @@ struct ECOORD return value == aOther.value; } - ///> Converts a size expressed in a certain unit to nanometers. + ///< Converts a size expressed in a certain unit to nanometers. static long long int ConvertToNm( int aValue, enum EAGLE_UNIT aUnit ); }; @@ -594,10 +587,10 @@ struct ERECT /** - * EATTR - * parses an Eagle "attribute" XML element. Note that an attribute element - * is different than an XML element attribute. The attribute element is a - * full XML node in and of itself, and has attributes of its own. Blame Eagle. + * Parse an Eagle "attribute" XML element. + * + * @note An attribute element is different than an XML element attribute. The attribute element + * is a full XML node in and of itself, and has attributes of its own. Blame Eagle. */ struct EATTR { diff --git a/common/preview_items/arc_geom_manager.cpp b/common/preview_items/arc_geom_manager.cpp index eabf4e5c39..a19bd1f81e 100644 --- a/common/preview_items/arc_geom_manager.cpp +++ b/common/preview_items/arc_geom_manager.cpp @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -28,7 +28,7 @@ using namespace KIGFX::PREVIEW; -///> Snap an angle to the nearest 45 degrees +///< Snap an angle to the nearest 45 degrees static double snapAngle( double aAngle ) { return KiROUND( aAngle / M_PI_4 ) * M_PI_4; diff --git a/common/preview_items/ruler_item.cpp b/common/preview_items/ruler_item.cpp index 9bebb2df2f..2b71176f77 100644 --- a/common/preview_items/ruler_item.cpp +++ b/common/preview_items/ruler_item.cpp @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -90,9 +90,9 @@ static double getTickLineWidth( const TEXT_DIMS& textDims, bool aDrawingDropShad */ struct TICK_FORMAT { - double divisionBase; ///> multiple from the last scale - int majorStep; ///> ticks between major ticks - int midStep; ///> ticks between medium ticks (0 if no medium ticks) + double divisionBase; ///< multiple from the last scale + int majorStep; ///< ticks between major ticks + int midStep; ///< ticks between medium ticks (0 if no medium ticks) }; diff --git a/common/tool/tool_dispatcher.cpp b/common/tool/tool_dispatcher.cpp index 90a2c31499..782cf8efda 100644 --- a/common/tool/tool_dispatcher.cpp +++ b/common/tool/tool_dispatcher.cpp @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN - * Copyright (C) 2013-2020 KiCad Developers, see CHANGELOG.txt for contributors. + * Copyright (C) 2013-2021 KiCad Developers, see CHANGELOG.txt for contributors. * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -43,7 +43,7 @@ #include #include -///> Stores information about a mouse button state +///< Stores information about a mouse button state struct TOOL_DISPATCHER::BUTTON_STATE { BUTTON_STATE( TOOL_MOUSE_BUTTONS aButton, const wxEventType& aDownEvent, @@ -57,45 +57,45 @@ struct TOOL_DISPATCHER::BUTTON_STATE dblClickEvent( aDblClickEvent ) {}; - ///> Flag indicating that dragging is active for the given button. + ///< Flag indicating that dragging is active for the given button. bool dragging; - ///> Flag indicating that the given button is pressed. + ///< Flag indicating that the given button is pressed. bool pressed; - ///> Point where dragging has started (in world coordinates). + ///< Point where dragging has started (in world coordinates). VECTOR2D dragOrigin; - ///> Point where click event has occurred. + ///< Point where click event has occurred. VECTOR2D downPosition; - ///> Difference between drag origin point and current mouse position (expressed as distance in - ///> pixels). + ///< Difference between drag origin point and current mouse position (expressed as distance in + ///< pixels). double dragMaxDelta; - ///> Determines the mouse button for which information are stored. + ///< Determines the mouse button for which information are stored. TOOL_MOUSE_BUTTONS button; - ///> The type of wxEvent that determines mouse button press. + ///< The type of wxEvent that determines mouse button press. wxEventType downEvent; - ///> The type of wxEvent that determines mouse button release. + ///< The type of wxEvent that determines mouse button release. wxEventType upEvent; - ///> The type of wxEvent that determines mouse button double click. + ///< The type of wxEvent that determines mouse button double click. wxEventType dblClickEvent; - ///> Time stamp for the last mouse button press event. + ///< Time stamp for the last mouse button press event. wxLongLong downTimestamp; - ///> Restores initial state. + ///< Restores initial state. void Reset() { dragging = false; pressed = false; } - ///> Checks the current state of the button. + ///< Checks the current state of the button. bool GetState() const { wxMouseState mouseState = wxGetMouseState(); @@ -251,6 +251,7 @@ bool TOOL_DISPATCHER::handleMouseButton( wxEvent& aEvent, int aIndex, bool aMoti return false; } + // Helper function to know if a special key ( see key list ) should be captured // or if the event can be skipped // on Linux, the event must be passed to the GUI if they are not used by KiCad, @@ -279,6 +280,7 @@ bool isKeySpecialCode( int aKeyCode ) return isInList; } + // Helper function to know if a key should be managed by DispatchWxEvent() // or if the event can be ignored and skipped because the key is only a modifier // that is not used alone in kicad @@ -430,7 +432,8 @@ void TOOL_DISPATCHER::DispatchWxEvent( wxEvent& aEvent ) wxWindow* focus = wxWindow::FindFocus(); // Required in win32 to ensure wxTimer events get scheduled in between other events - // Or else we may stall them out entirely and never get them during actions like rapid mouse moves + // Or else we may stall them out entirely and never get them during actions like rapid + // mouse moves. KIPLATFORM::APP::ForceTimerMessagesToBeCreatedIfNecessary(); wxEventType type = aEvent.GetEventType(); @@ -607,7 +610,8 @@ void TOOL_DISPATCHER::DispatchWxEvent( wxEvent& aEvent ) // Not handled wxEVT_CHAR must be Skipped (sent to GUI). // Otherwise accelerators and shortcuts in main menu or toolbars are not seen. // Escape key presses are never skipped by the handler since they correspond to tool cancel - // events, and if they aren't skipped then they are propagated to other frames (which we don't want). + // events, and if they aren't skipped then they are propagated to other frames (which we + // don't want). if( (type == wxEVT_CHAR || type == wxEVT_CHAR_HOOK) && !keyIsSpecial && !handled diff --git a/common/tool/tool_manager.cpp b/common/tool/tool_manager.cpp index 9ce915c3bb..c363e791a9 100644 --- a/common/tool/tool_manager.cpp +++ b/common/tool/tool_manager.cpp @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2018 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -144,8 +144,7 @@ struct TOOL_MANAGER::TOOL_STATE } /** - * Function Push() - * Stores the current state of the tool on stack. Stacks are stored internally and are not + * Store the current state of the tool on stack. Stacks are stored internally and are not * shared between different TOOL_STATE objects. */ void Push() @@ -156,9 +155,9 @@ struct TOOL_MANAGER::TOOL_STATE } /** - * Function Pop() - * Restores state of the tool from stack. Stacks are stored internally and are not + * Restore state of the tool from stack. Stacks are stored internally and are not * shared between different TOOL_STATE objects. + * * @return True if state was restored, false if the stack was empty. */ bool Pop() @@ -179,10 +178,10 @@ struct TOOL_MANAGER::TOOL_STATE } private: - ///> Stack preserving previous states of a TOOL. + ///< Stack preserving previous states of a TOOL. std::stack> stateStack; - ///> Restores the initial state. + ///< Restores the initial state. void clear() { idle = true; diff --git a/common/view/view.cpp b/common/view/view.cpp index d29a914c88..3e1fdc5be6 100644 --- a/common/view/view.cpp +++ b/common/view/view.cpp @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -70,8 +72,7 @@ private: friend class VIEW; /** - * Function getLayers() - * Returns layer numbers used by the item. + * Return layer numbers used by the item. * * @param aLayers[]: output layer index array * @param aCount: number of layer indices in aLayers[] @@ -91,17 +92,16 @@ private: int m_requiredUpdate; ///< Flag required for updating int m_drawPriority; ///< Order to draw this item in a layer, lowest first - ///> Helper for storing cached items group ids + ///< Helper for storing cached items group ids typedef std::pair GroupPair; - ///> Indexes of cached GAL display lists corresponding to the item (for every layer it occupies). - ///> (in the std::pair "first" stores layer number, "second" stores group id). + ///< Indexes of cached GAL display lists corresponding to the item (for every layer it. + ///< occupies)(in the std::pair "first" stores layer number, "second" stores group id). GroupPair* m_groups; int m_groupsSize; /** - * Function getGroup() - * Returns number of the group id for the given layer, or -1 in case it was not cached before. + * Return number of the group id for the given layer, or -1 in case it was not cached before. * * @param aLayer is the layer number for which group id is queried. * @return group id or -1 in case there is no group id (ie. item is not cached). @@ -118,8 +118,7 @@ private: } /** - * Function setGroup() - * Sets a group id for the item and the layer combination. + * Set a group id for the item and the layer combination. * * @param aLayer is the layer numbe. * @param aGroup is the group id. @@ -151,8 +150,7 @@ private: /** - * Function deleteGroups() - * Removes all of the stored group ids. Forces recaching of the item. + * Remove all of the stored group ids. Forces recaching of the item. */ void deleteGroups() { @@ -163,8 +161,7 @@ private: /** - * Function storesGroups() - * Returns information if the item uses at least one group id (ie. if it is cached at all). + * Return information if the item uses at least one group id (ie. if it is cached at all). * * @returns true in case it is cached at least for one layer. */ @@ -175,7 +172,8 @@ private: /** - * Reorders the stored groups (to facilitate reordering of layers) + * Reorder the stored groups (to facilitate reordering of layers). + * * @see VIEW::ReorderLayerData * * @param aReorderMap is the mapping of old to new layer ids @@ -202,8 +200,7 @@ private: std::vector m_layers; /** - * Function saveLayers() - * Saves layers used by the item. + * Save layers used by the item. * * @param aLayers is an array containing layer numbers to be saved. * @param aCount is the size of the array. @@ -222,8 +219,7 @@ private: } /** - * Function viewRequiredUpdate() - * Returns current update flag for an item. + * Return current update flag for an item. */ int requiredUpdate() const { @@ -231,8 +227,7 @@ private: } /** - * Function clearUpdateFlags() - * Marks an item as already updated, so it is not going to be redrawn. + * Mark an item as already updated, so it is not going to be redrawn. */ void clearUpdateFlags() { @@ -240,8 +235,7 @@ private: } /** - * Function isRenderable() - * Returns if the item should be drawn or not. + * Return if the item should be drawn or not. */ bool isRenderable() const { @@ -1198,7 +1192,8 @@ void VIEW::invalidateItem( VIEW_ITEM* aItem, int aUpdateFlags ) } else { - // updateLayers updates geometry too, so we do not have to update both of them at the same time + // updateLayers updates geometry too, so we do not have to update both of them at the + // same time if( aUpdateFlags & LAYERS ) { updateLayers( aItem ); diff --git a/include/board_printout.h b/include/board_printout.h index faf02650ee..be4c68f05d 100644 --- a/include/board_printout.h +++ b/include/board_printout.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2009 Jean-Pierre Charras, jean-pierre.charras@ujf-grenoble.fr - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2018 CERN * Author: Maciej Suminski * @@ -90,34 +90,34 @@ public: * * @param aLayerName a text which can be printed as layer name. * @param aPageNum the number of the current page (only used to print this value). - * @param aPageCount the number of pages to ptint (only used to print this value). + * @param aPageCount the number of pages to print (only used to print this value). */ virtual void DrawPage( const wxString& aLayerName = wxEmptyString, 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 + ///< Enables layers visibility for a printout virtual void setupViewLayers( KIGFX::VIEW& aView, const LSET& aLayerSet ); - ///> Configures PAINTER object for a printout + ///< Configures PAINTER object for a printout virtual void setupPainter( KIGFX::PAINTER& aPainter ); - ///> Configures GAL object for a printout + ///< Configures GAL object for a printout virtual void setupGal( KIGFX::GAL* aGal ); - ///> Returns bounding box of the printed objects (excluding worksheet frame) + ///< Returns bounding box of the printed objects (excluding worksheet frame) virtual EDA_RECT getBoundingBox() = 0; - ///> Returns a PAINTER instance used to draw the items. + ///< Returns a PAINTER instance used to draw the items. virtual std::unique_ptr 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; }; diff --git a/include/commit.h b/include/commit.h index 0e07790085..01b8e89a6c 100644 --- a/include/commit.h +++ b/include/commit.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2016-2017 CERN - * Copyright (C) 2020 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see change_log.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -34,15 +35,15 @@ class EDA_ITEM; -///> Types of changes +///< Types of changes enum CHANGE_TYPE { CHT_ADD = 1, CHT_REMOVE = 2, CHT_MODIFY = 4, CHT_TYPE = CHT_ADD | CHT_REMOVE | CHT_MODIFY, - ///> Flag to indicate the change is already applied, - ///> just notify observers (not compatible with CHT_MODIFY) + ///< Flag to indicate the change is already applied, + ///< just notify observers (not compatible with CHT_MODIFY) CHT_DONE = 8, CHT_FLAGS = CHT_DONE }; @@ -73,39 +74,39 @@ public: COMMIT(); virtual ~COMMIT(); - ///> Adds a new item to the model + ///< Add a new item to the model COMMIT& Add( EDA_ITEM* aItem ) { return Stage( aItem, CHT_ADD ); } - ///> Notifies observers that aItem has been added + ///< Notify observers that aItem has been added COMMIT& Added( EDA_ITEM* aItem ) { return Stage( aItem, CHT_ADD | CHT_DONE ); } - ///> Removes a new item from the model + ///< Remove a new item from the model COMMIT& Remove( EDA_ITEM* aItem ) { return Stage( aItem, CHT_REMOVE ); } - ///> Notifies observers that aItem has been removed + ///< Notify observers that aItem has been removed COMMIT& Removed( EDA_ITEM* aItem ) { return Stage( aItem, CHT_REMOVE | CHT_DONE ); } - ///> Modifies a given item in the model. - ///> Must be called before modification is performed. + ///< Modify a given item in the model. + ///< Must be called before modification is performed. COMMIT& Modify( EDA_ITEM* aItem ) { return Stage( aItem, CHT_MODIFY ); } - ///> Creates 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. Requires a copy done + ///< before the modification. COMMIT& Modified( EDA_ITEM* aItem, EDA_ITEM* aCopy ) { return createModified( aItem, aCopy ); @@ -121,7 +122,7 @@ public: return *this; } - ///> Adds 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 ); virtual COMMIT& Stage( std::vector& container, CHANGE_TYPE aChangeType ); @@ -129,11 +130,11 @@ public: virtual COMMIT& Stage( const PICKED_ITEMS_LIST& aItems, UNDO_REDO aModFlag = UNDO_REDO::UNSPECIFIED ); - ///> Executes the changes. + ///< Execute the changes. virtual void Push( const wxString& aMessage = wxT( "A commit" ), bool aCreateUndoEntry = true, bool aSetDirtyBit = true ) = 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 @@ -141,15 +142,15 @@ public: return m_changes.empty(); } - ///> Returns status of an item. + ///< Returns status of an item. int GetStatus( EDA_ITEM* aItem ); protected: struct COMMIT_LINE { - EDA_ITEM* m_item; ///> Main item that is added/deleted/modified - EDA_ITEM* m_copy; ///> Optional copy of the item - CHANGE_TYPE m_type; ///> Modification type + EDA_ITEM* m_item; ///< Main item that is added/deleted/modified + EDA_ITEM* m_copy; ///< Optional copy of the item + CHANGE_TYPE m_type; ///< Modification type }; // Should be called in Push() & Revert() methods diff --git a/include/common.h b/include/common.h index 173c6c3cc8..df74ff331e 100644 --- a/include/common.h +++ b/include/common.h @@ -4,7 +4,7 @@ * Copyright (C) 2014-2020 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2007-2015 SoftPLC Corporation, Dick Hollenbeck * Copyright (C) 2008 Wayne Stambaugh - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -148,7 +148,7 @@ wxString GetOSXKicadDataDir(); // this function, so add it if missing #if !wxCHECK_VERSION( 3, 1, 0 ) #define USE_KICAD_WXSTRING_HASH // for common.cpp -///> Template specialization to enable wxStrings for certain containers (e.g. unordered_map) +///< Template specialization to enable wxStrings for certain containers (e.g. unordered_map) namespace std { template<> struct hash diff --git a/include/confirm.h b/include/confirm.h index ddfc62a8b9..abfd8c1d6b 100644 --- a/include/confirm.h +++ b/include/confirm.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2007 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -23,7 +23,8 @@ */ /** - * This file is part of the common library + * This file is part of the common library. + * * @file confirm.h * @see common.h */ @@ -44,7 +45,7 @@ class wxStaticBitmap; class KIDIALOG : public wxRichMessageDialog { public: - ///> Dialog type. Selects appropriate icon and default dialog title + ///< Dialog type. Selects appropriate icon and default dialog title enum KD_TYPE { KD_NONE, KD_INFO, KD_QUESTION, KD_WARNING, KD_ERROR }; KIDIALOG( wxWindow* aParent, const wxString& aMessage, const wxString& aCaption, @@ -58,10 +59,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(); @@ -154,7 +155,7 @@ void DisplayInfoMessage( wxWindow* parent, const wxString& aMessage, bool IsOK( wxWindow* aParent, const wxString& aMessage ); /** - * Displays a warning dialog with \a aMessage and returns the user response. + * Display a warning dialog with \a aMessage and returns the user response. * * @param aParent is the parent window. NULL can be used if the parent is the top level window. * @param aWarning is the warning to display in the top part of the dialog box using a bold font. @@ -174,7 +175,7 @@ int OKOrCancelDialog( wxWindow* aParent, const wxString& aWarning, const wxStrin /** - * Displays a dialog with radioboxes asking the user to select an option. + * Display a dialog with radioboxes asking the user to select an option. * * @param aParent is the parent window. * @param aTitle is the dialog title. @@ -183,6 +184,6 @@ int OKOrCancelDialog( wxWindow* aParent, const wxString& aWarning, const wxStrin * @return Index of the selected option or -1 when the dialog has been canceled. */ int SelectSingleOption( wxWindow* aParent, const wxString& aTitle, const wxString& aMessage, - const wxArrayString& aOptions ); + const wxArrayString& aOptions ); #endif /* __INCLUDE__CONFIRM_H__ */ diff --git a/include/cursors.h b/include/cursors.h index 38236821ca..f61cff6637 100644 --- a/include/cursors.h +++ b/include/cursors.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see CHANGELOG.TXT for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see CHANGELOG.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -76,21 +76,21 @@ public: */ struct CURSOR_DEF { - ///> The ID key used to uniquely identify a cursor in a given store + ///< The ID key used to uniquely identify a cursor in a given store KICURSOR m_id_key; - ///> The image data bitmap + ///< The image data bitmap const unsigned char* m_image_data; - ///> The mask data bitmap + ///< The mask data bitmap const unsigned char* m_mask_data; const char** m_xpm; - ///> The image size in pixels + ///< The image size in pixels wxSize m_size; - ///> The "hotspot" where the cursor "is" in the image + ///< The "hotspot" where the cursor "is" in the image wxPoint m_hotspot; }; @@ -116,7 +116,7 @@ public: static const wxStockCursor GetStockCursor( KICURSOR aCursorType ); private: - ///> Internal store of cursors by ID + ///< Internal store of cursors by ID std::map m_store; }; diff --git a/include/dialogs/dialog_color_picker.h b/include/dialogs/dialog_color_picker.h index c4757a1326..31501cfd57 100644 --- a/include/dialogs/dialog_color_picker.h +++ b/include/dialogs/dialog_color_picker.h @@ -5,7 +5,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2018-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -84,9 +84,10 @@ public: * Dialog constructor * @param aParent is the caller * @param aCurrentColor is the current color, used to show it in dialog - * @param aAllowOpacityControl = true to allow opacity (alpha channel) setting + * @param aAllowOpacityControl true to allow opacity (alpha channel) setting * false to not show this setting (opacity = 1.0 always) - * @param aUserColors: if not null is a list of defined colors replacing the dialog predefined colors + * @param aUserColors if not null is a list of defined colors replacing the dialog + * predefined colors */ DIALOG_COLOR_PICKER( wxWindow* aParent, const KIGFX::COLOR4D& aCurrentColor, bool aAllowOpacityControl, CUSTOM_COLORS_LIST* aUserColors = nullptr, @@ -105,7 +106,7 @@ private: bool m_allowMouseEvents; bool m_allowOpacityCtrl; ///< true to show the widget, ///< false to keep alpha channel = 1.0 - KIGFX::COLOR4D m_previousColor4D; ///< the inital color4d + KIGFX::COLOR4D m_previousColor4D; ///< the initial color4d KIGFX::COLOR4D m_newColor4D; ///< the current color4d KIGFX::COLOR4D m_defaultColor; ///< The default color4d @@ -117,7 +118,7 @@ private: wxPoint m_cursorBitmapGreen; ///< the green cursor on the RGB bitmap palette. wxPoint m_cursorBitmapBlue; ///< the blue cursor on the RGB bitmap palette. wxPoint m_cursorBitmapHSV; ///< the cursor on the HSV bitmap palette. - wxPoint* m_selectedCursor; ///< the ref cursor to the selected curor, if any, or null. + wxPoint* m_selectedCursor; ///< the ref cursor to the selected cursor, if any, or null. double m_hue; ///< the current hue, in degrees (0 ... 360) double m_sat; ///< the current saturation (0 ... 1.0) @@ -136,7 +137,7 @@ private: void createRGBBitmap(); ///< generate the bitmap that shows the RVB color space void drawRGBPalette(); ///< draws the RVB color space - ///> repaint a static bitmap with the aColor4D color + ///< repaint a static bitmap with the aColor4D color void updatePreview( wxStaticBitmap* aStaticBitmap, KIGFX::COLOR4D& aColor4D ); ///< Event handler from wxSlider: brightness (value) control @@ -152,7 +153,7 @@ private: void OnChangeEditHue( wxSpinEvent& event ) override; void OnChangeEditSat( wxSpinEvent& event ) override; - ///> mouse handlers, when clicking on a palette bitmap + ///< mouse handlers, when clicking on a palette bitmap void onRGBMouseClick( wxMouseEvent& event ) override; void onRGBMouseDrag( wxMouseEvent& event ) override; void onHSVMouseClick( wxMouseEvent& event ) override; @@ -163,8 +164,9 @@ private: ///< Event handler for the reset button press void OnResetButton( wxCommandEvent& aEvent ) override; - /** manage the Hue and Saturation settings when the mouse cursor - * is at aMouseCursor. + /** + * Manage the Hue and Saturation settings when the mouse cursor is at aMouseCursor. + * * @param aMouseCursor is the mouse cursor position on the HSV bitmap * @return true if the Hue and Saturation can be set from aMouseCursor, * if Saturation value computed from aMouseCursor is <= 1.0, @@ -172,14 +174,16 @@ private: */ bool setHSvaluesFromCursor( wxPoint aMouseCursor ); - ///> Event handler for defined color buttons + ///< Event handler for defined color buttons void buttColorClick( wxMouseEvent& event ); - ///> called when creating the dialog + ///< called when creating the dialog bool TransferDataToWindow() override; - /** creates the bitmap buttons for each defined colors - * if aPredefinedColors is nullptr, a internal predefined list will be used + /** + * Create the bitmap buttons for each defined colors. + * + * If aPredefinedColors is nullptr, a internal predefined list will be used. */ void initDefinedColors( CUSTOM_COLORS_LIST* aPredefinedColors ); diff --git a/include/env_paths.h b/include/env_paths.h index 5d3a29337f..3c84346cfe 100644 --- a/include/env_paths.h +++ b/include/env_paths.h @@ -2,8 +2,9 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2017 Wayne Stambaugh - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2017 CERN + * * @author Maciej Suminski * * This program is free software: you can redistribute it and/or modify it @@ -20,7 +21,7 @@ * with this program. If not, see . */ -///> Helper functions to substitute paths with environmental variables. +///< Helper functions to substitute paths with environmental variables. #ifndef ENV_PATHS_H #define ENV_PATHS_H @@ -28,45 +29,46 @@ #include /** - * Normalizes a file path to an environmental variable, if possible. + * Normalize a file path to an environmental variable, if possible. * * @param aFilePath is the full file path (path and file name) to be normalized. - * @param aEnvVars is an optional map of environmental variables to try substition with. + * @param aEnvVars is an optional map of environmental variables to try substitution with. * @param aProject is an optional project, to normalize the file path to the project path. * @return Normalized full file path (path and file name) if succeeded or empty string if the - * path could not be normalized. + * path could not be normalized. */ wxString NormalizePath( const wxFileName& aFilePath, const ENV_VAR_MAP* aEnvVars, const PROJECT* aProject ); /** - * Normalizes a file path to an environmental variable, if possible. + * Normalize a file path to an environmental variable, if possible. * * @param aFilePath is the full file path (path and file name) to be normalized. - * @param aEnvVars is an optional map of environmental variables to try substition with. + * @param aEnvVars is an optional map of environmental variables to try substitution with. * @param aProjectPath is an optional string to normalize the file path to the project path. * @return Normalized full file path (path and file name) if succeeded or empty string if the - * path could not be normalized. + * path could not be normalized. */ wxString NormalizePath( const wxFileName& aFilePath, const ENV_VAR_MAP* aEnvVars, const wxString& aProjectPath ); /** - * Searches the default paths trying to find one with the requested file. + * Search the default paths trying to find one with the requested file. * * @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 - * an empty string. + * an empty string. */ wxString ResolveFile( const wxString& aFileName, const ENV_VAR_MAP* aEnvVars, const PROJECT* aProject ); /** - * Checks if a given filename is within a given project directory (not whether it exists!) + * Check if a given filename is within a given project directory (not whether it exists!) + * * @param aFileName is the absolute path to check - * @param aProject is the project to test agains + * @param aProject is the project to test against * @param aSubPath will be filled with the relative path to the file inside the project (if any) * @return true if aFileName's path is inside aProject's path */ diff --git a/include/gal/cairo/cairo_gal.h b/include/gal/cairo/cairo_gal.h index 715ea452ed..2e3971589c 100644 --- a/include/gal/cairo/cairo_gal.h +++ b/include/gal/cairo/cairo_gal.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de - * Copyright (C) 2012-2020 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2017-2018 CERN * @author Maciej Suminski * @@ -40,7 +40,7 @@ #include /** - * Class CAIRO_GAL is the cairo implementation of the graphics abstraction layer. + * The Cairo implementation of the graphics abstraction layer. * * Quote from Wikipedia: * " Cairo is a software library used to provide a vector graphics-based, device-independent @@ -213,7 +213,7 @@ public: void EnableDepthTest( bool aEnabled = false ) override; - ///> @copydoc GAL::DrawGrid() + ///< @copydoc GAL::DrawGrid() void DrawGrid() override; @@ -264,17 +264,17 @@ protected: void storePath(); ///< Store the actual path /** - * Blits cursor into the current screen. + * Blit cursor into the current screen. */ void blitCursor( wxMemoryDC& clientDC ); - /// Drawing polygons & polylines is the same in cairo, so here is the common code + /// Drawing polygons & polylines is the same in Cairo, so here is the common code void drawPoly( const std::deque& aPointList ); void drawPoly( const VECTOR2D aPointList[], int aListSize ); void drawPoly( const SHAPE_LINE_CHAIN& aLineChain ); /** - * Returns a valid key that can be used as a new group number. + * Return a valid key that can be used as a new group number. * * @return An unique group number that is not used by any other group. */ @@ -369,7 +369,7 @@ public: ~CAIRO_GAL(); - ///> @copydoc GAL::IsVisible() + ///< @copydoc GAL::IsVisible() bool IsVisible() const override { return IsShownOnScreen() && !GetClientRect().IsEmpty(); @@ -443,7 +443,7 @@ public: */ void skipMouseEvent( wxMouseEvent& aEvent ); - ///> Cairo-specific update handlers + ///< Cairo-specific update handlers bool updatedGalDisplayOptions( const GAL_DISPLAY_OPTIONS& aOptions ) override; protected: @@ -462,7 +462,7 @@ protected: unsigned char* wxOutput; ///< wxImage compatible buffer // Variables related to Cairo <-> wxWidgets - unsigned char* bitmapBuffer; ///< Storage of the cairo image + unsigned char* bitmapBuffer; ///< Storage of the Cairo image int stride; ///< Stride value for Cairo int wxBufferWidth; bool isInitialized; ///< Are Cairo image & surface ready to use diff --git a/include/gal/cairo/cairo_print.h b/include/gal/cairo/cairo_print.h index 6106b14bf3..8131af355d 100644 --- a/include/gal/cairo/cairo_print.h +++ b/include/gal/cairo/cairo_print.h @@ -1,6 +1,6 @@ /* * Copyright (C) 2018 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * Author: Maciej Suminski * Author: Tomasz Wlostowski @@ -71,7 +71,7 @@ private: cairo_surface_t* m_surface; #ifdef __WXMSW__ - ///> DC handle on Windows + ///< DC handle on Windows void* m_hdc; // the real type is HDC, but do not pull in extra headers #endif /* __WXMSW__ */ @@ -110,17 +110,17 @@ public: void SetSheetSize( const VECTOR2D& aSize ) override; private: - ///> Returns true if page orientation is landscape + ///< Returns true if page orientation is landscape bool isLandscape() const { return m_nativePaperSize.x > m_nativePaperSize.y; } - ///> Printout size + ///< Printout size VECTOR2D m_nativePaperSize; - ///> Flag indicating whether the platform rotates page automatically or - ///> GAL needs to handle it in the transformation matrix + ///< Flag indicating whether the platform rotates page automatically or + ///< GAL needs to handle it in the transformation matrix bool m_hasNativeLandscapeRotation; std::unique_ptr m_printCtx; diff --git a/include/gal/gal_display_options.h b/include/gal/gal_display_options.h index 2ed2f4b51f..5b1aad8852 100644 --- a/include/gal/gal_display_options.h +++ b/include/gal/gal_display_options.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KICAD, a free EDA CAD application. * -* Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. +* Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -86,7 +86,7 @@ namespace KIGFX GAL_DISPLAY_OPTIONS(); /** - * Read GAL config options from applicaton-level config + * Read GAL config options from application-level config * @param aCfg the window settings to load from */ void ReadWindowSettings( WINDOW_SETTINGS& aCfg ); @@ -120,28 +120,28 @@ namespace KIGFX DPI_SCALING m_dpi; - ///> The grid style to draw the grid in + ///< The grid style to draw the grid in KIGFX::GRID_STYLE m_gridStyle; - ///> Snapping options for the grid + ///< Snapping options for the grid GRID_SNAPPING m_gridSnapping; - ///> Thickness to render grid lines/dots + ///< Thickness to render grid lines/dots double m_gridLineWidth; - ///> Minimum pixel distance between displayed grid lines + ///< Minimum pixel distance between displayed grid lines double m_gridMinSpacing; - ///> Whether or not to draw the coordinate system axes + ///< Whether or not to draw the coordinate system axes bool m_axesEnabled; - ///> Fullscreen crosshair or small cross + ///< Fullscreen crosshair or small cross bool m_fullscreenCursor; - ///> Force cursor display + ///< Force cursor display bool m_forceDisplayCursor; - ///> The pixel scale factor (>1 for hi-DPI scaled displays) + ///< The pixel scale factor (>1 for hi-DPI scaled displays) double m_scaleFactor; }; diff --git a/include/gal/graphics_abstraction_layer.h b/include/gal/graphics_abstraction_layer.h index 4cdc6f275f..ace04040a6 100644 --- a/include/gal/graphics_abstraction_layer.h +++ b/include/gal/graphics_abstraction_layer.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de - * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. * * Graphics Abstraction Layer (GAL) - base class * @@ -47,10 +47,10 @@ namespace KIGFX { /** - * Class GAL is the abstract interface for drawing on a 2D-surface. + * Abstract interface for drawing on a 2D-surface. * * The functions are optimized for drawing shapes of an EDA-program such as KiCad. Most methods - * are abstract and need to be implemented by a lower layer, for example by a cairo or OpenGL + * are abstract and need to be implemented by a lower layer, for example by a Cairo or OpenGL * implementation. Almost all methods use world coordinates as arguments. The board design is * defined in world space units for drawing purposes these are transformed to screen units with * this layer. So zooming is handled here as well. @@ -69,16 +69,16 @@ public: GAL( GAL_DISPLAY_OPTIONS& aOptions ); virtual ~GAL(); - /// Returns the initialization status for the canvas. + /// Return the initialization status for the canvas. virtual bool IsInitialized() const { return true; } - /// Returns true if the GAL canvas is visible on the screen. + /// Return true if the GAL canvas is visible on the screen. virtual bool IsVisible() const { return true; } - /// Returns true if the GAL engine is a cairo based type. + /// Return true if the GAL engine is a Cairo based type. virtual bool IsCairoEngine() { return false; } - /// Returns true if the GAL engine is a OpenGL based type. + /// Return true if the GAL engine is a OpenGL based type. virtual bool IsOpenGlEngine() { return false; } // --------------- @@ -198,13 +198,13 @@ public: // Screen methods // -------------- - /// Resizes the canvas. + /// Resize the canvas. virtual void ResizeScreen( int aWidth, int aHeight ) {}; - /// Shows/hides the GAL canvas + /// Show/hide the GAL canvas virtual bool Show( bool aShow ) { return true; }; - /// Returns GAL canvas size in pixels + /// Return GAL canvas size in pixels const VECTOR2I& GetScreenPixelSize() const { return screenSize; @@ -337,7 +337,7 @@ public: } /** - * Draws a vector type text using preloaded Newstroke font. + * Draw a vector type text using preloaded Newstroke font. * * @param aText is the text to be drawn. * @param aPosition is the text position in world coordinates. @@ -350,7 +350,7 @@ public: } /** - * Draws a text using a bitmap font. It should be faster than StrokeText(), + * Draw a text using a bitmap font. It should be faster than StrokeText(), * but can be used only for non-Gerber elements. * * @param aText is the text to be drawn. @@ -373,8 +373,7 @@ public: } /** - * Compute the X and Y size of a given text. The text is expected to be - * a only one line text. + * Compute the X and Y size of a given text. The text is expected to be a only one line text. * * @param aText is the text string (one line). * @return is the text size. @@ -389,7 +388,7 @@ public: virtual void SetTextAttributes( const EDA_TEXT* aText ); /** - * Reset text attributes to default styling + * Reset text attributes to default styling. * * Normally, custom attributes will be set individually after this, * otherwise you can use SetTextAttributes() @@ -442,7 +441,7 @@ public: } /** - * Returns current text horizontal justification setting. + * Return current text horizontal justification setting. */ inline EDA_TEXT_HJUSTIFY_T GetHorizontalJustify() const { @@ -531,7 +530,7 @@ public: virtual void DrawGroup( int aGroupNumber ) {}; /** - * Changes the color used to draw the group. + * Change the color used to draw the group. * * @param aGroupNumber is the group number. * @param aNewColor is the new color. @@ -539,7 +538,7 @@ public: virtual void ChangeGroupColor( int aGroupNumber, const COLOR4D& aNewColor ) {}; /** - * Changes the depth (Z-axis position) of the group. + * Change the depth (Z-axis position) of the group. * * @param aGroupNumber is the group number. * @param aDepth is the new depth. @@ -703,7 +702,7 @@ public: } /** - * Returns the minimum depth in the currently used range (the top). + * Return the minimum depth in the currently used range (the top). */ inline double GetMinDepth() const { @@ -711,7 +710,7 @@ public: } /** - * Returns the maximum depth in the currently used range (the bottom). + * Return the maximum depth in the currently used range (the bottom). */ inline double GetMaxDepth() const { @@ -761,28 +760,28 @@ public: // --------------------------- /** - * Sets the target for rendering. + * Set the target for rendering. * * @param aTarget is the new target for rendering. */ virtual void SetTarget( RENDER_TARGET aTarget ) {}; /** - * Gets the currently used target for rendering. + * Get the currently used target for rendering. * * @return The current rendering target. */ virtual RENDER_TARGET GetTarget() const { return TARGET_CACHED; }; /** - * Clears the target for rendering. + * Clear the target for rendering. * * @param aTarget is the target to be cleared. */ virtual void ClearTarget( RENDER_TARGET aTarget ) {}; /** - * Returns true if the target exists. + * Return true if the target exists. * * @param aTarget is the target to be checked. */ @@ -792,7 +791,7 @@ public: }; /** - * Sets negative draw mode in the renderer + * Set negative draw mode in the renderer. * * When negative mode is enabled, drawn items will subtract from * previously drawn items. This is mainly needed for Gerber @@ -809,7 +808,7 @@ public: // ------------- /** - * Sets the visibility setting of the grid. + * Set the visibility setting of the grid. * * @param aVisibility is the new visibility setting of the grid. */ @@ -861,7 +860,7 @@ public: } /** - * Returns the grid size. + * Return the grid size. * * @return A vector containing the grid size in x and y direction. */ @@ -891,7 +890,7 @@ public: } /** - * Enables drawing the axes. + * Enable drawing the axes. */ inline void SetAxesEnabled( bool aAxesEnabled ) { @@ -918,7 +917,7 @@ public: return gridLineWidth; } - ///> Draw the grid + ///< Draw the grid virtual void DrawGrid() {}; /** @@ -962,7 +961,7 @@ public: } /** - * Returns information about cursor visibility. + * Return information about cursor visibility. * * @return True if cursor is visible. */ @@ -989,7 +988,7 @@ public: virtual void DrawCursor( const VECTOR2D& aCursorPosition ) {}; /** - * Changes the current depth to deeper, so it is possible to draw objects right beneath + * Change the current depth to deeper, so it is possible to draw objects right beneath * other. */ inline void AdvanceDepth() @@ -998,7 +997,7 @@ public: } /** - * Stores current drawing depth on the depth stack. + * Store current drawing depth on the depth stack. */ inline void PushDepth() { @@ -1006,7 +1005,7 @@ public: } /** - * Restores previously stored drawing depth for the depth stack. + * Restore previously stored drawing depth for the depth stack. */ inline void PopDepth() { @@ -1026,16 +1025,16 @@ public: } protected: - /// Private: use GAL_CONTEXT_LOCKER RAII object + /// Use GAL_CONTEXT_LOCKER RAII object virtual void lockContext( int aClientCookie ) {} virtual void unlockContext( int aClientCookie ) {} - /// Enables item update mode. + /// Enable item update mode. /// Private: use GAL_UPDATE_CONTEXT RAII object virtual void beginUpdate() {} - /// Disables item update mode. + /// Disable item update mode. virtual void endUpdate() {} /// Begin the drawing, needs to be called for every new frame. @@ -1067,7 +1066,7 @@ protected: static const int GRID_DEPTH; /** - * Gets the actual cursor color to draw + * Get the actual cursor color to draw */ COLOR4D getCursorColor() const; @@ -1075,7 +1074,7 @@ protected: // Settings observer interface // --------------- /** - * Handler for observer settings changes + * Handler for observer settings changes. */ void OnGalDisplayOptionsChanged( const GAL_DISPLAY_OPTIONS& aOptions ) override; diff --git a/include/gal/opengl/cached_container.h b/include/gal/opengl/cached_container.h index 41b9611b52..4a05d25387 100644 --- a/include/gal/opengl/cached_container.h +++ b/include/gal/opengl/cached_container.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2013-2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @@ -54,19 +54,19 @@ public: return true; } - ///> @copydoc VERTEX_CONTAINER::SetItem() + ///< @copydoc VERTEX_CONTAINER::SetItem() virtual void SetItem( VERTEX_ITEM* aItem ) override; - ///> @copydoc VERTEX_CONTAINER::FinishItem() + ///< @copydoc VERTEX_CONTAINER::FinishItem() virtual void FinishItem() override; - ///> @copydoc VERTEX_CONTAINER::Allocate() + ///< @copydoc VERTEX_CONTAINER::Allocate() virtual VERTEX* Allocate( unsigned int aSize ) override; - ///> @copydoc VERTEX_CONTAINER::Delete() + ///< @copydoc VERTEX_CONTAINER::Delete() virtual void Delete( VERTEX_ITEM* aItem ) override; - ///> @copydoc VERTEX_CONTAINER::Clear() + ///< @copydoc VERTEX_CONTAINER::Clear() virtual void Clear() override; /** @@ -79,14 +79,14 @@ public: */ virtual bool IsMapped() const = 0; - ///> @copydoc VERTEX_CONTAINER::Map() + ///< @copydoc VERTEX_CONTAINER::Map() virtual void Map() override = 0; - ///> @copydoc VERTEX_CONTAINER::Unmap() + ///< @copydoc VERTEX_CONTAINER::Unmap() virtual void Unmap() override = 0; protected: - ///> Maps size of free memory chunks to their offsets + ///< Maps size of free memory chunks to their offsets typedef std::pair CHUNK; typedef std::multimap FREE_CHUNK_MAP; @@ -153,20 +153,20 @@ protected: */ void addFreeChunk( unsigned int aOffset, unsigned int aSize ); - ///> Store size & offset of free chunks. + ///< Store size & offset of free chunks. FREE_CHUNK_MAP m_freeChunks; - ///> Stored VERTEX_ITEMs + ///< Stored VERTEX_ITEMs ITEMS m_items; - ///> Currently modified item + ///< Currently modified item VERTEX_ITEM* m_item; - ///> Properties of currently modified chunk & item + ///< Properties of currently modified chunk & item unsigned int m_chunkSize; unsigned int m_chunkOffset; - ///> Maximal vertex index number stored in the container + ///< Maximal vertex index number stored in the container unsigned int m_maxIndex; private: diff --git a/include/gal/opengl/cached_container_gpu.h b/include/gal/opengl/cached_container_gpu.h index e59d08ffb7..93390666c2 100644 --- a/include/gal/opengl/cached_container_gpu.h +++ b/include/gal/opengl/cached_container_gpu.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2013-2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @@ -35,7 +35,6 @@ namespace KIGFX /** * Specialization of CACHED_CONTAINER that stores data in video memory via memory mapping. */ - class CACHED_CONTAINER_GPU : public CACHED_CONTAINER { public: @@ -52,10 +51,10 @@ public: return m_isMapped; } - ///> @copydoc VERTEX_CONTAINER::Map() + ///< @copydoc VERTEX_CONTAINER::Map() void Map() override; - ///> @copydoc VERTEX_CONTAINER::Unmap() + ///< @copydoc VERTEX_CONTAINER::Unmap() void Unmap() override; protected: @@ -71,13 +70,13 @@ protected: bool defragmentResize( unsigned int aNewSize ) override; bool defragmentResizeMemcpy( unsigned int aNewSize ); - ///> Flag saying if vertex buffer is currently mapped + ///< Flag saying if vertex buffer is currently mapped bool m_isMapped; - ///> Vertex buffer handle + ///< Vertex buffer handle unsigned int m_glBufferHandle; - ///> Flag saying whether it is safe to use glCopyBufferSubData + ///< Flag saying whether it is safe to use glCopyBufferSubData bool m_useCopyBuffer; }; } // namespace KIGFX diff --git a/include/gal/opengl/cached_container_ram.h b/include/gal/opengl/cached_container_ram.h index dfd96364c6..ed6e61acca 100644 --- a/include/gal/opengl/cached_container_ram.h +++ b/include/gal/opengl/cached_container_ram.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2013-2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @@ -48,10 +48,10 @@ public: CACHED_CONTAINER_RAM( unsigned int aSize = DEFAULT_SIZE ); ~CACHED_CONTAINER_RAM(); - ///> @copydoc VERTEX_CONTAINER::Unmap() + ///< @copydoc VERTEX_CONTAINER::Unmap() void Map() override {} - ///> @copydoc VERTEX_CONTAINER::Unmap() + ///< @copydoc VERTEX_CONTAINER::Unmap() void Unmap() override; bool IsMapped() const override @@ -78,7 +78,7 @@ protected: */ bool defragmentResize( unsigned int aNewSize ) override; - ///> Handle to vertices buffer + ///< Handle to vertices buffer GLuint m_verticesBuffer; }; } // namespace KIGFX diff --git a/include/gal/opengl/gpu_manager.h b/include/gal/opengl/gpu_manager.h index de1916fcc0..dbbf524019 100644 --- a/include/gal/opengl/gpu_manager.h +++ b/include/gal/opengl/gpu_manager.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @@ -66,7 +66,7 @@ public: virtual void DrawAll() = 0; /** - * Clears the container after drawing routines. + * Clear the container after drawing routines. */ virtual void EndDrawing() = 0; @@ -85,19 +85,19 @@ public: protected: GPU_MANAGER( VERTEX_CONTAINER* aContainer ); - ///> Drawing status flag. + ///< Drawing status flag. bool m_isDrawing; - ///> Container that stores vertices data. + ///< Container that stores vertices data. VERTEX_CONTAINER* m_container; - ///> Shader handling + ///< Shader handling SHADER* m_shader; - ///> Location of shader attributes (for glVertexAttribPointer) + ///< Location of shader attributes (for glVertexAttribPointer) int m_shaderAttrib; - ///> true: enable Z test when drawing + ///< true: enable Z test when drawing bool m_enableDepthTest; }; @@ -108,44 +108,44 @@ public: GPU_CACHED_MANAGER( VERTEX_CONTAINER* aContainer ); ~GPU_CACHED_MANAGER(); - ///> @copydoc GPU_MANAGER::BeginDrawing() + ///< @copydoc GPU_MANAGER::BeginDrawing() virtual void BeginDrawing() override; - ///> @copydoc GPU_MANAGER::DrawIndices() + ///< @copydoc GPU_MANAGER::DrawIndices() virtual void DrawIndices( unsigned int aOffset, unsigned int aSize ) override; - ///> @copydoc GPU_MANAGER::DrawAll() + ///< @copydoc GPU_MANAGER::DrawAll() virtual void DrawAll() override; - ///> @copydoc GPU_MANAGER::EndDrawing() + ///< @copydoc GPU_MANAGER::EndDrawing() virtual void EndDrawing() override; - ///> Maps vertex buffer stored in GPU memory. + ///< Map vertex buffer stored in GPU memory. void Map(); - ///> Unmaps vertex buffer. + ///< Unmap vertex buffer. void Unmap(); protected: - ///> Resizes the indices buffer to aNewSize if necessary + ///< Resizes the indices buffer to aNewSize if necessary void resizeIndices( unsigned int aNewSize ); - ///> Buffers initialization flag + ///< Buffers initialization flag bool m_buffersInitialized; - ///> Pointer to the current indices buffer + ///< Pointer to the current indices buffer boost::scoped_array m_indices; - ///> Pointer to the first free cell in the indices buffer + ///< Pointer to the first free cell in the indices buffer GLuint* m_indicesPtr; - ///> Handle to indices buffer + ///< Handle to indices buffer GLuint m_indicesBuffer; - ///> Number of indices stored in the indices buffer + ///< Number of indices stored in the indices buffer unsigned int m_indicesSize; - ///> Current indices buffer size + ///< Current indices buffer size unsigned int m_indicesCapacity; }; @@ -155,16 +155,16 @@ class GPU_NONCACHED_MANAGER : public GPU_MANAGER public: GPU_NONCACHED_MANAGER( VERTEX_CONTAINER* aContainer ); - ///> @copydoc GPU_MANAGER::BeginDrawing() + ///< @copydoc GPU_MANAGER::BeginDrawing() virtual void BeginDrawing() override; - ///> @copydoc GPU_MANAGER::DrawIndices() + ///< @copydoc GPU_MANAGER::DrawIndices() virtual void DrawIndices( unsigned int aOffset, unsigned int aSize ) override; - ///> @copydoc GPU_MANAGER::DrawAll() + ///< @copydoc GPU_MANAGER::DrawAll() virtual void DrawAll() override; - ///> @copydoc GPU_MANAGER::EndDrawing() + ///< @copydoc GPU_MANAGER::EndDrawing() virtual void EndDrawing() override; }; } // namespace KIGFX diff --git a/include/gal/opengl/opengl_gal.h b/include/gal/opengl/opengl_gal.h index 523610a4cc..cbdc4a155d 100644 --- a/include/gal/opengl/opengl_gal.h +++ b/include/gal/opengl/opengl_gal.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de - * Copyright (C) 2020 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2013-2017 CERN * @author Maciej Suminski * @@ -56,7 +56,7 @@ class SHADER; class GL_BITMAP_CACHE; /** - * @brief Class OpenGL_GAL is the OpenGL implementation of the Graphics Abstraction Layer. + * OpenGL implementation of the Graphics Abstraction Layer. * * This is a direct OpenGL-implementation and uses low-level graphics primitives like triangles * and quads. The purpose is to provide a fast graphics interface, that takes advantage of modern @@ -66,8 +66,6 @@ class OPENGL_GAL : public GAL, public HIDPI_GL_CANVAS { public: /** - * @brief Constructor OPENGL_GAL - * * @param aParent is the wxWidgets immediate wxWindow parent of this object. * * @param aMouseListener is the wxEvtHandler that should receive the mouse events, @@ -87,7 +85,8 @@ public: ~OPENGL_GAL(); /** - * @brief Checks OpenGL features + * Checks OpenGL features. + * * @param aOptions * @return wxEmptyString if OpenGL 2.1 or greater is available, otherwise returns error message */ @@ -102,7 +101,7 @@ public: return IsShownOnScreen() && !GetClientRect().IsEmpty(); } - ///> @copydoc GAL::IsVisible() + ///< @copydoc GAL::IsVisible() bool IsVisible() const override { return IsShownOnScreen() && !GetClientRect().IsEmpty(); @@ -302,30 +301,32 @@ private: // Vertex buffer objects related fields typedef std::unordered_map< unsigned int, std::shared_ptr > GROUPS_MAP; - GROUPS_MAP groups; ///< Stores informations about VBO objects (groups) - unsigned int groupCounter; ///< Counter used for generating keys for groups - VERTEX_MANAGER* currentManager; ///< Currently used VERTEX_MANAGER (for storing VERTEX_ITEMs) - VERTEX_MANAGER* cachedManager; ///< Container for storing cached VERTEX_ITEMs - VERTEX_MANAGER* nonCachedManager; ///< Container for storing non-cached VERTEX_ITEMs - VERTEX_MANAGER* overlayManager; ///< Container for storing overlaid VERTEX_ITEMs + GROUPS_MAP groups; ///< Stores information about VBO objects (groups) + unsigned int groupCounter; ///< Counter used for generating keys for groups + VERTEX_MANAGER* currentManager; ///< Currently used VERTEX_MANAGER (for storing + ///< VERTEX_ITEMs). + VERTEX_MANAGER* cachedManager; ///< Container for storing cached VERTEX_ITEMs + VERTEX_MANAGER* nonCachedManager; ///< Container for storing non-cached VERTEX_ITEMs + VERTEX_MANAGER* overlayManager; ///< Container for storing overlaid VERTEX_ITEMs // Framebuffer & compositing - OPENGL_COMPOSITOR* compositor; ///< Handles multiple rendering targets - unsigned int mainBuffer; ///< Main rendering target - unsigned int overlayBuffer; ///< Auxiliary rendering target (for menus etc.) - RENDER_TARGET currentTarget; ///< Current rendering target + OPENGL_COMPOSITOR* compositor; ///< Handles multiple rendering targets + unsigned int mainBuffer; ///< Main rendering target + unsigned int overlayBuffer; ///< Auxiliary rendering target (for menus etc.) + RENDER_TARGET currentTarget; ///< Current rendering target // Shader - SHADER* shader; ///< There is only one shader used for different objects + SHADER* shader; ///< There is only one shader used for different + ///< objects. // Internal flags bool isFramebufferInitialized; ///< Are the framebuffers initialized? static bool isBitmapFontLoaded; ///< Is the bitmap font texture loaded? bool isBitmapFontInitialized; ///< Is the shader set to use bitmap fonts? - bool isInitialized; ///< Basic initialization flag, has to be done - ///< when the window is visible - bool isGrouping; ///< Was a group started? - bool m_isContextLocked; ///< Used for assertion checking + bool isInitialized; ///< Basic initialization flag, has to be done + ///< when the window is visible + bool isGrouping; ///< Was a group started? + bool m_isContextLocked; ///< Used for assertion checking int lockClientCookie; GLint ufm_worldPixelSize; GLint ufm_screenPixelSize; @@ -367,8 +368,10 @@ private: void drawLineQuad( const VECTOR2D& aStartPoint, const VECTOR2D& aEndPoint ); /** - * @brief Draw a semicircle. Depending on settings (isStrokeEnabled & isFilledEnabled) it runs - * the proper function (drawStrokedSemiCircle or drawFilledSemiCircle). + * Draw a semicircle. + * + * Depending on settings (isStrokeEnabled & isFilledEnabled) it runs the proper function + * (drawStrokedSemiCircle or drawFilledSemiCircle). * * @param aCenterPoint is the center point. * @param aRadius is the radius of the semicircle. @@ -378,7 +381,7 @@ private: void drawSemiCircle( const VECTOR2D& aCenterPoint, double aRadius, double aAngle ); /** - * @brief Draw a filled semicircle. + *Draw a filled semicircle. * * @param aCenterPoint is the center point. * @param aRadius is the radius of the semicircle. @@ -388,7 +391,7 @@ private: void drawFilledSemiCircle( const VECTOR2D& aCenterPoint, double aRadius, double aAngle ); /** - * @brief Draw a stroked semicircle. + * Draw a stroked semicircle. * * @param aCenterPoint is the center point. * @param aRadius is the radius of the semicircle. @@ -398,28 +401,31 @@ private: void drawStrokedSemiCircle( const VECTOR2D& aCenterPoint, double aRadius, double aAngle ); /** - * @brief Generic way of drawing a polyline stored in different containers. + * Generic way of drawing a polyline stored in different containers. + * * @param aPointGetter is a function to obtain coordinates of n-th vertex. * @param aPointCount is the number of points to be drawn. */ void drawPolyline( const std::function& aPointGetter, int aPointCount ); /** - * @brief Draws a filled polygon. It does not need the last point to have the same coordinates + * Draw a filled polygon. It does not need the last point to have the same coordinates * as the first one. + * * @param aPoints is the vertices data (3 coordinates: x, y, z). * @param aPointCount is the number of points. */ void drawPolygon( GLdouble* aPoints, int aPointCount ); /** - * @brief Draws a set of polygons with a cached triangulation. Way faster than drawPolygon. + * Draw a set of polygons with a cached triangulation. Way faster than drawPolygon. */ void drawTriangulatedPolyset( const SHAPE_POLY_SET& aPoly ); /** - * @brief Draws a single character using bitmap font. + * Draw a single character using bitmap font. + * * Its main purpose is to be used in BitmapText() function. * * @param aChar is the character to be drawn. @@ -428,7 +434,8 @@ private: int drawBitmapChar( unsigned long aChar ); /** - * @brief Draws an overbar over the currently drawn text. + * Draw an overbar over the currently drawn text. + * * Its main purpose is to be used in BitmapText() function. * This method requires appropriate scaling to be applied (as is done in BitmapText() function). * The current X coordinate will be the overbar ending. @@ -439,7 +446,7 @@ private: void drawBitmapOverbar( double aLength, double aHeight ); /** - * @brief Computes a size of text drawn using bitmap font with current text setting applied. + * Compute a size of text drawn using bitmap font with current text setting applied. * * @param aText is the text to be drawn. * @return Pair containing text bounding box and common Y axis offset. The values are expressed @@ -449,33 +456,33 @@ private: // Event handling /** - * @brief This is the OnPaint event handler. + * This is the OnPaint event handler. * * @param aEvent is the OnPaint event. */ void onPaint( wxPaintEvent& aEvent ); /** - * @brief Skip the mouse event to the parent. + * Skip the mouse event to the parent. * * @param aEvent is the mouse event. */ void skipMouseEvent( wxMouseEvent& aEvent ); /** - * @brief Blits cursor into the current screen. + * Blit cursor into the current screen. */ void blitCursor(); /** - * @brief Returns a valid key that can be used as a new group number. + * Return a valid key that can be used as a new group number. * * @return An unique group number that is not used by any other group. */ unsigned int getNewGroupNumber(); /** - * @brief Compute the angle step when drawing arcs/circles approximated with lines. + * Compute the angle step when drawing arcs/circles approximated with lines. */ double calcAngleStep( double aRadius ) const { @@ -488,7 +495,8 @@ private: VECTOR2D getScreenPixelSize() const; /** - * @brief Basic OpenGL initialization and feature checks + * Basic OpenGL initialization and feature checks. + * * @throw std::runtime_error if any of the OpenGL feature checks failed */ void init(); diff --git a/include/gal/opengl/vertex_common.h b/include/gal/opengl/vertex_common.h index 945374c930..9c97981095 100644 --- a/include/gal/opengl/vertex_common.h +++ b/include/gal/opengl/vertex_common.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -38,7 +40,8 @@ namespace KIGFX { -///> Possible types of shaders (keep consistent with the actual shader source in gl_builtin_shaders.cpp) +///< Possible types of shaders (keep consistent with the actual shader source in +///< gl_builtin_shaders.cpp). enum SHADER_MODE { SHADER_NONE = 0, @@ -53,7 +56,7 @@ enum SHADER_MODE SHADER_LINE_F = 10 }; -///> Data structure for vertices {X,Y,Z,R,G,B,A,shader¶m} +///< Data structure for vertices {X,Y,Z,R,G,B,A,shader¶m} struct VERTEX { GLfloat x, y, z; // Coordinates diff --git a/include/gal/opengl/vertex_container.h b/include/gal/opengl/vertex_container.h index 7cbe276393..9457982376 100644 --- a/include/gal/opengl/vertex_container.h +++ b/include/gal/opengl/vertex_container.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2013-2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @@ -167,16 +167,16 @@ protected: return m_currentSize - m_freeSpace; } - ///> Free space left in the container, expressed in vertices + ///< Free space left in the container, expressed in vertices unsigned int m_freeSpace; - ///> Current container size, expressed in vertices + ///< Current container size, expressed in vertices unsigned int m_currentSize; - ///> Store the initial size, so it can be resized to this on Clear() + ///< Store the initial size, so it can be resized to this on Clear() unsigned int m_initialSize; - ///> Actual storage memory + ///< Actual storage memory VERTEX* m_vertices; // Status flags diff --git a/include/gal/stroke_font.h b/include/gal/stroke_font.h index b266a9b25f..d24f77da7f 100644 --- a/include/gal/stroke_font.h +++ b/include/gal/stroke_font.h @@ -3,8 +3,9 @@ * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de * Copyright (C) 2013 CERN + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski - * Copyright (C) 2016-2020 Kicad Developers, see AUTHORS.txt for contributors. * * Stroke font class * @@ -46,7 +47,7 @@ typedef std::vector*> GLYPH; typedef std::vector GLYPH_LIST; /** - * Class STROKE_FONT implements stroke font drawing. + * Implement a stroke font drawing. * * A stroke font is composed of lines. */ @@ -142,7 +143,7 @@ private: BOX2D computeBoundingBox( const GLYPH* aGlyph, double aGlyphWidth ) const; /** - * Draws a single line of text. Multiline texts should be split before using the + * Draw a single line of text. Multiline texts should be split before using the * function. * * @param aText is the text to be drawn. @@ -168,21 +169,21 @@ private: const GLYPH_LIST* m_glyphs; ///< Glyph list const std::vector* m_glyphBoundingBoxes; ///< Bounding boxes of the glyphs - ///> Factor that determines relative vertical position of the overbar. + ///< Factor that determines relative vertical position of the overbar. static const double OVERBAR_POSITION_FACTOR; static const double UNDERLINE_POSITION_FACTOR; - ///> Factor that determines relative line width for bold text. + ///< Factor that determines relative line width for bold text. static const double BOLD_FACTOR; - ///> Scale factor for a glyph + ///< Scale factor for a glyph static const double STROKE_FONT_SCALE; - ///> Tilt factor for italic style (the is is the scaling factor - ///> on dY relative coordinates to give a tilst shape + ///< Tilt factor for italic style (the is is the scaling factor + ///< on dY relative coordinates to give a tilt shape static const double ITALIC_TILT; - ///> Factor that determines the pitch between 2 lines. + ///< Factor that determines the pitch between 2 lines. static const double INTERLINE_PITCH_RATIO; }; } // namespace KIGFX diff --git a/include/gl_context_mgr.h b/include/gl_context_mgr.h index 38a6d0d41c..777398b6f3 100644 --- a/include/gl_context_mgr.h +++ b/include/gl_context_mgr.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 CERN - * Copyright (C) 2020 KiCad Developers, see CHANGELOG.TXT for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -85,13 +86,13 @@ public: void UnlockCtx( wxGLContext* aContext ); private: - ///> Map of GL contexts & their parent canvases. + ///< Map of GL contexts & their parent canvases. std::map m_glContexts; - ///> Currently bound GL context. + ///< Currently bound GL context. wxGLContext* m_glCtx; - ///> Lock to prevent unexpected GL context switching. + ///< Lock to prevent unexpected GL context switching. std::mutex m_glCtxMutex; // Singleton diff --git a/include/hash_eda.h b/include/hash_eda.h index 7ea56f7df5..c9e2ae41c5 100644 --- a/include/hash_eda.h +++ b/include/hash_eda.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -25,6 +26,7 @@ #ifndef HASH_EDA_H_ #define HASH_EDA_H_ + /** * @brief Hashing functions for EDA_ITEMs. */ @@ -34,13 +36,13 @@ class EDA_ITEM; -///> Enables/disables properties that will be used for calculating the hash. -///> The properties might be combined using the bitwise 'or' operator. +///< Enables/disables 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, HASH_ROT = 0x04, HASH_LAYER = 0x08, @@ -51,7 +53,8 @@ enum HASH_FLAGS }; /** - * Calculates hash of an EDA_ITEM. + * Calculate hash of an EDA_ITEM. + * * @param aItem is the item for which the hash will be computed. * @return Hash value. */ @@ -64,7 +67,8 @@ std::size_t hash_fp_item( const EDA_ITEM* aItem, int aFlags = HASH_FLAGS::HASH_A static inline void hash_combine( std::size_t &seed ) {} /** - * @brief Combine multiple hashes utilizing previous hash result + * Combine multiple hashes utilizing previous hash result. + * * @tparam T A hashable type * @param seed A seed value input and output for the result. * @param val A hashable object of type T diff --git a/include/intrusive_list.h b/include/intrusive_list.h index 3d74071dc9..f4604a1cdd 100644 --- a/include/intrusive_list.h +++ b/include/intrusive_list.h @@ -2,6 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2017 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -25,7 +27,7 @@ #ifndef INTRUSIVE_LIST_H #define INTRUSIVE_LIST_H -///> A lightweight intrusive list container +///< A lightweight intrusive list container template class INTRUSIVE_LIST { diff --git a/include/multivector.h b/include/multivector.h index cad971db7b..09ebb3b732 100644 --- a/include/multivector.h +++ b/include/multivector.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2017 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @author Bernhard Stegmaier @@ -106,7 +106,6 @@ public: protected: /** - * Constructor. * @param aItems is the container to wrap. * @param aIt is the iterator to initialize this iterator (usually some begin() or end() * iterator). @@ -121,7 +120,7 @@ public: m_filter = ( aType != UNDEFINED_TYPE ); } - ///> Assures the iterator is in a valid state. + ///< Assures the iterator is in a valid state. void validate() { // for all-items iterators (unfiltered): check if this is the end of the @@ -145,25 +144,25 @@ public: } } - ///> Wrapped container + ///< Wrapped container ITEM_CONTAINER* m_parent; - ///> Iterator for one of the ptr_vector containers stored in the array + ///< Iterator for one of the ptr_vector containers stored in the array ITEM_CONTAINER_IT m_it; - ///> Flag indicating whether type filtering is enabled + ///< Flag indicating whether type filtering is enabled bool m_filter; - ///> Type of the currently iterated items + ///< Type of the currently iterated items int m_curType; friend class MULTIVECTOR; }; - ///> The non-const iterator + ///< The non-const iterator typedef ITERATOR_BASE, typename ITEM_PTR_VECTOR::iterator> ITERATOR; - ///> The const iterator + ///< The const iterator typedef ITERATOR_BASE, typename ITEM_PTR_VECTOR::const_iterator> CONST_ITERATOR; @@ -295,7 +294,7 @@ public: static constexpr int TYPES_COUNT = LAST_TYPE - FIRST_TYPE + 1; private: - ///> Get first non-empty type or first type if all are empty. + ///< Get first non-empty type or first type if all are empty. int first() const { int i = 0; @@ -306,7 +305,7 @@ private: return ( i == TYPES_COUNT ) ? FIRST_TYPE : FIRST_TYPE + i; } - ///> Get last non-empty type or first type if all are empty. + ///< Get last non-empty type or first type if all are empty. int last() const { int i = TYPES_COUNT - 1; @@ -317,7 +316,7 @@ private: return ( i < 0 ) ? FIRST_TYPE : FIRST_TYPE + i; } - ///> Contained items by type + ///< Contained items by type ITEM_PTR_VECTOR m_data[TYPES_COUNT]; }; diff --git a/include/origin_viewitem.h b/include/origin_viewitem.h index f1ae2e9d52..6e872f8bee 100644 --- a/include/origin_viewitem.h +++ b/include/origin_viewitem.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -41,7 +42,7 @@ namespace KIGFX { class ORIGIN_VIEWITEM : public EDA_ITEM { public: - ///> Marker symbol styles + ///< Marker symbol styles enum MARKER_STYLE { NO_GRAPHIC, CROSS, X, DOT, CIRCLE_CROSS, CIRCLE_X, CIRCLE_DOT, DASH_LINE @@ -150,22 +151,22 @@ public: } protected: - ///> Marker coordinates. + ///< Marker coordinates. VECTOR2D m_position; - ///> Marker end position for markers that stretch between points + ///< Marker end position for markers that stretch between points VECTOR2D m_end; - ///> Marker size (in pixels). + ///< Marker size (in pixels). int m_size; - ///> Marker color. + ///< Marker color. COLOR4D m_color; - ///> Marker symbol. + ///< Marker symbol. MARKER_STYLE m_style; - ///> If set, the marker will be drawn even if its position is 0,0 + ///< If set, the marker will be drawn even if its position is 0,0 bool m_drawAtZero; }; diff --git a/include/pcb_group.h b/include/pcb_group.h index 395930590c..6629e8d4f9 100644 --- a/include/pcb_group.h +++ b/include/pcb_group.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 Joshua Redstone redstone at gmail.com - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -40,7 +40,7 @@ class VIEW; } /** - * PCB_GROUP is a set of BOARD_ITEMs (i.e., without duplicates) + * A set of BOARD_ITEMs (i.e., without duplicates). * * The group parent is always board, not logical parent group. The group is transparent * container - e.g., its position is derived from the position of its members. A selection @@ -76,14 +76,14 @@ public: } /** - * Adds item to group. Does not take ownership of item. + * Add item to group. Does not take ownership of item. * * @return true if item was added (false if item belongs to a different group). */ bool AddItem( BOARD_ITEM* aItem ); /** - * Removes item from group. + * Remove item from group. * * @return true if item was removed (false if item was not in the group). */ @@ -92,7 +92,7 @@ public: void RemoveAll(); /* - * Searches for highest level group containing item. + * Search for highest level group containing item. * * @param aScope restricts the search to groups within the group scope. * @param aFootprintEditor true if we should stop promoting at the footprint level @@ -109,22 +109,22 @@ public: } #endif - ///> @copydoc EDA_ITEM::GetPosition + ///< @copydoc EDA_ITEM::GetPosition wxPoint GetPosition() const override; - ///> @copydoc EDA_ITEM::SetPosition + ///< @copydoc EDA_ITEM::SetPosition void SetPosition( const wxPoint& aNewpos ) override; - ///> @copydoc BOARD_ITEM::GetLayerSet + ///< @copydoc BOARD_ITEM::GetLayerSet LSET GetLayerSet() const override; - ///> @copydoc BOARD_ITEM::SetLayer + ///< @copydoc BOARD_ITEM::SetLayer void SetLayer( PCB_LAYER_ID aLayer ) override { wxFAIL_MSG( "groups don't support layer SetLayer" ); } - ///> @copydoc EDA_ITEM::Clone + ///< @copydoc EDA_ITEM::Clone EDA_ITEM* Clone() const override; /* @@ -137,51 +137,51 @@ public: */ PCB_GROUP* DeepDuplicate() const; - ///> @copydoc BOARD_ITEM::SwapData + ///< @copydoc BOARD_ITEM::SwapData void SwapData( BOARD_ITEM* aImage ) override; - ///> @copydoc BOARD_ITEM::IsOnLayer + ///< @copydoc BOARD_ITEM::IsOnLayer bool IsOnLayer( PCB_LAYER_ID aLayer ) const override; - ///> @copydoc EDA_ITEM::HitTest + ///< @copydoc EDA_ITEM::HitTest bool HitTest( const wxPoint& aPosition, int aAccuracy = 0 ) const override; - ///> @copydoc EDA_ITEM::HitTest + ///< @copydoc EDA_ITEM::HitTest bool HitTest( const EDA_RECT& aRect, bool aContained, int aAccuracy = 0 ) const override; - ///> @copydoc EDA_ITEM::GetBoundingBox + ///< @copydoc EDA_ITEM::GetBoundingBox const EDA_RECT GetBoundingBox() const override; - ///> @copydoc EDA_ITEM::Visit + ///< @copydoc EDA_ITEM::Visit SEARCH_RESULT Visit( INSPECTOR aInspector, void* aTestData, const KICAD_T aScanTypes[] ) override; - ///> @copydoc VIEW_ITEM::ViewGetLayers + ///< @copydoc VIEW_ITEM::ViewGetLayers void ViewGetLayers( int aLayers[], int& aCount ) const override; - ///> @copydoc VIEW_ITEM::ViewGetLOD + ///< @copydoc VIEW_ITEM::ViewGetLOD double ViewGetLOD( int aLayer, KIGFX::VIEW* aView ) const override; - ///> @copydoc BOARD_ITEM::Move + ///< @copydoc BOARD_ITEM::Move void Move( const wxPoint& aMoveVector ) override; - ///> @copydoc BOARD_ITEM::Rotate + ///< @copydoc BOARD_ITEM::Rotate void Rotate( const wxPoint& aRotCentre, double aAngle ) override; - ///> @copydoc BOARD_ITEM::Flip + ///< @copydoc BOARD_ITEM::Flip void Flip( const wxPoint& aCentre, bool aFlipLeftRight ) override; - ///> @copydoc EDA_ITEM::GetSelectMenuText + ///< @copydoc EDA_ITEM::GetSelectMenuText wxString GetSelectMenuText( EDA_UNITS aUnits ) const override; - ///> @copydoc EDA_ITEM::GetMenuImage + ///< @copydoc EDA_ITEM::GetMenuImage BITMAP_DEF GetMenuImage() const override; - ///> @copydoc EDA_ITEM::GetMsgPanelInfo + ///< @copydoc EDA_ITEM::GetMsgPanelInfo void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; /** - * Invokes a function on all members of the group. + * Invoke a function on all members of the group. * * @note This function should not add or remove items to the group. * @@ -190,7 +190,7 @@ public: void RunOnChildren( const std::function& aFunction ) const; /** - * Invokes a function on all descendants of the group. + * Invoke a function on all descendants of the group. * * @note This function should not add or remove items to the group or descendant groups. * @param aFunction is the function to be invoked. diff --git a/include/preview_items/arc_geom_manager.h b/include/preview_items/arc_geom_manager.h index 8a85896492..3cddbc1cd8 100644 --- a/include/preview_items/arc_geom_manager.h +++ b/include/preview_items/arc_geom_manager.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -31,16 +31,12 @@ namespace PREVIEW { /** - * ARC_GEOM_MANAGER - * - * A class to manage the construction of a circular arc though - * sequential setting of critical points: centre, arc start - * and arc end. The manager is driven by setting cursor points, which + * Manage the construction of a circular arc though sequential setting of critical points: + * center, arc start and arc end. The manager is driven by setting cursor points, which * update the geometry, and optionally advance the manager state. * - * Interfaces are provided to return both arc geometry (can be used - * to set up real arcs on PCBs, for example) as well as important - * control points for informational overlays. + * Interfaces are provided to return both arc geometry (can be used to set up real arcs on + * PCBs, for example) as well as important control points for informational overlays. */ class ARC_GEOM_MANAGER: public MULTISTEP_GEOM_MANAGER { @@ -50,9 +46,9 @@ public: enum ARC_STEPS { - SET_ORIGIN = 0, ///> Waiting to lock in origin point - SET_START, ///> Waiting to lock in the arc start point - SET_ANGLE, ///> Waiting to lock in the arc end point + SET_ORIGIN = 0, ///< Waiting to lock in origin point + SET_START, ///< Waiting to lock in the arc start point + SET_ANGLE, ///< Waiting to lock in the arc end point COMPLETE }; @@ -62,7 +58,7 @@ public: } /** - * Get the current step the mananger is on (useful when drawing + * Get the current step the manager is on (useful when drawing * something depends on the current state) */ ARC_STEPS GetStep() const @@ -72,13 +68,13 @@ public: bool acceptPoint( const VECTOR2I& aPt ) override; - ///> The the arc to be clockwise from start + ///< The the arc to be clockwise from start void SetClockwise( bool aCw ); - ///> Reverse the current are direction + ///< Reverse the current are direction void ToggleClockwise(); - ///> Set angle snapping (for the next point) + ///< Set angle snapping (for the next point) void SetAngleSnap( bool aSnap ) { m_angleSnap = aSnap; @@ -88,22 +84,22 @@ public: * Geometry query interface - used by clients of the manager */ - ///> Get the centre point of the arc (valid when state > SET_ORIGIN) + ///< Get the center point of the arc (valid when state > SET_ORIGIN) VECTOR2I GetOrigin() const; - ///> Get the coordinates of the arc start + ///< Get the coordinates of the arc start VECTOR2I GetStartRadiusEnd() const; - ///> Get the coordinates of the arc end point + ///< Get the coordinates of the arc end point VECTOR2I GetEndRadiusEnd() const; - ///> Get the radius of the arc (valid if step >= SET_START) + ///< Get the radius of the arc (valid if step >= SET_START) double GetRadius() const; - ///> Get the angle of the vector leading to the start point (valid if step >= SET_START) + ///< Get the angle of the vector leading to the start point (valid if step >= SET_START) double GetStartAngle() const; - ///> Get the angle of the vector leading to the end point (valid if step >= SET_ANGLE) + ///< Get the angle of the vector leading to the end point (valid if step >= SET_ANGLE) double GetSubtended() const; private: @@ -112,13 +108,13 @@ private: * Point acceptor functions */ - ///> Set the centre point of the arc + ///< Set the center point of the arc bool setOrigin( const VECTOR2I& aOrigin ); - ///> Set the end of the first radius line (arc start) + ///< Set the end of the first radius line (arc start) bool setStart( const VECTOR2I& aEnd ); - ///> Set a point of the second radius line (collinear with arc end) + ///< Set a point of the second radius line (collinear with arc end) bool setEnd( const VECTOR2I& aCursor ); /* diff --git a/include/preview_items/centreline_rect_item.h b/include/preview_items/centreline_rect_item.h index 62a1c4340f..be9c90f4c3 100644 --- a/include/preview_items/centreline_rect_item.h +++ b/include/preview_items/centreline_rect_item.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -40,36 +40,31 @@ namespace PREVIEW class TWO_POINT_GEOMETRY_MANAGER; /** - * CENTRELINE_RECT_ITEM + * Represent an area drawn by drawing a rectangle of a given aspect along a vector, with the + * midpoint of one side on the start point and the mid point of the opposite side on the end. * - * Represents an area drawn by drawing a rectangle of a given aspect - * along a vector, with the midpoiunt of one side on the start point - * and the mid point of the opposite side on the end. - * - * The centre line does not have to horizontal or vertical, it - * can be at any angle. + * The center line does not have to horizontal or vertical, it can be at any angle. */ class CENTRELINE_RECT_ITEM : public SIMPLE_OVERLAY_ITEM { public: - CENTRELINE_RECT_ITEM( const TWO_POINT_GEOMETRY_MANAGER& aGeomMgr, - double aAspect ); + CENTRELINE_RECT_ITEM( const TWO_POINT_GEOMETRY_MANAGER& aGeomMgr, double aAspect ); - ///> Gets the bounding box of the rectangle + ///< Gets the bounding box of the rectangle virtual const BOX2I ViewBBox() const override; private: - ///> Get the rectangular outline + ///< Get the rectangular outline SHAPE_POLY_SET getOutline() const; - ///> Draw rectangle and centre line onto GAL + ///< Draw rectangle and center line onto GAL void drawPreviewShape( KIGFX::VIEW* aView ) const override; const TWO_POINT_GEOMETRY_MANAGER& m_geomMgr; - ///> The aspect ratio of the rectangle to draw + ///< The aspect ratio of the rectangle to draw double m_aspect; }; diff --git a/include/preview_items/multistep_geom_manager.h b/include/preview_items/multistep_geom_manager.h index 2e7c2dd7cc..478de64085 100644 --- a/include/preview_items/multistep_geom_manager.h +++ b/include/preview_items/multistep_geom_manager.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -53,9 +53,9 @@ public: * Add a point to the construction manager * * @param aPt the new point - * @param aLockIn whether to "lock in" the point, and move the - * geometry manager to the next (or previous) step. False to - * update geometry and not affect manager state + * @param aLockIn whether to "lock in" the point, and move the geometry manager to the + * next (or previous) step. False to update geometry and not affect + * manager state. */ void AddPoint( const VECTOR2I& aPt, bool aLockIn ) { @@ -73,16 +73,14 @@ public: } /** - * Undo the last point, and move the manager back to the previous - * step + * Undo the last point, and move the manager back to the previous step. */ void RemoveLastPoint() { performStep( false ); - // process the last point again, but in the previous step mode - // it doesn't matter if accepted or not, as long as the geometry - // is regenerated if needed + // process the last point again, but in the previous step mode it doesn't matter if + // accepted or not, as long as the geometry is regenerated if needed. acceptPoint( GetLastPoint() ); setGeometryChanged(); } @@ -96,7 +94,7 @@ public: } /** - * Reset the manager to the initial state + * Reset the manager to the initial state. */ void Reset() { @@ -105,7 +103,7 @@ public: } /** - * @return true if the manager reached the final state + * @return true if the manager reached the final state. */ bool IsComplete() const { @@ -113,10 +111,10 @@ public: } /** - * Gets the last point added (locked in or not). This can - * be useful when drawing previews, as the point given isn't always - * what gets locked into the geometry, if that step doesn't have - * full degrees of freedom + * Get the last point added (locked in or not). + * + * This can* be useful when drawing previews, as the point given isn't always what gets + * locked into the geometry, if that step doesn't have full degrees of freedom. */ VECTOR2I GetLastPoint() const { @@ -124,8 +122,7 @@ public: } /** - * @return true if the geoemtry has changed, eg such that a client - * should redraw + * @return true if the geometry has changed, eg such that a client should redraw. */ bool HasGeometryChanged() const { @@ -133,8 +130,8 @@ public: } /** - * Clear the geometry changed flag, call after the client code has - * updated everything as needed. + * Clear the geometry changed flag, call after the client code has updated everything + * as needed. */ void ClearGeometryChanged() { @@ -143,13 +140,13 @@ public: protected: - ///> Mark the geometry as changed for clients to notice + ///< Mark the geometry as changed for clients to notice void setGeometryChanged() { m_changed = true; } - ///> Get the current stage of the manager + ///< Get the current stage of the manager int getStep() const { return m_step; @@ -157,17 +154,17 @@ protected: private: - ///> Function that accepts a point for a stage, or rejects it - ///> to return to the previous stage + ///< Function that accepts a point for a stage, or rejects it + ///< to return to the previous stage virtual bool acceptPoint( const VECTOR2I& aPt ) = 0; /** - * The highest step this manager has - used to recognise completion + * The highest step this manager has - used to recognize completion * and to clamp the step as it advances. */ virtual int getMaxStep() const = 0; - ///> Moves the manager forward or backward through the stages + ///< Moves the manager forward or backward through the stages void performStep( bool aForward ) { m_step += aForward ? 1 : -1; @@ -176,15 +173,14 @@ private: m_step = std::min( std::max( m_step, 0 ), getMaxStep() ); } - ///> Has the gemotry changed such that a client should redraw? + ///< Has the geometry changed such that a client should redraw? bool m_changed = false; - ///> The last (raw) point added, which is usually the cursor position + ///< The last (raw) point added, which is usually the cursor position VECTOR2I m_lastPoint; /** - * The current manager step, from 0 to some highest number that - * depends on the manager + * The current manager step, from 0 to some highest number that depends on the manager. */ int m_step = 0; }; diff --git a/include/preview_items/polygon_geom_manager.h b/include/preview_items/polygon_geom_manager.h index 9a9a21ffa4..9f73fa7173 100644 --- a/include/preview_items/polygon_geom_manager.h +++ b/include/preview_items/polygon_geom_manager.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KICAD, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -27,9 +27,8 @@ #include /** - * Class that handles the drawing of a polygon, including - * management of last corner deletion and drawing of leader lines - * with various constraints (eg 45 deg only). + * Class that handles the drawing of a polygon, including management of last corner deletion + * and drawing of leader lines with various constraints (eg 45 deg only). * * This class handles only the geometry of the process. */ @@ -46,17 +45,17 @@ public: public: /** * Called before the first point is added - clients can do - * initialisation here, and can veto the start of the process + * initialization here, and can veto the start of the process * (e.g. if user cancels a dialog) * * @return false to veto start of new polygon */ virtual bool OnFirstPoint( POLYGON_GEOM_MANAGER& aMgr ) = 0; - ///> Sent when the polygon geometry changes + ///< Sent when the polygon geometry changes virtual void OnGeometryChange( const POLYGON_GEOM_MANAGER& aMgr ) = 0; - ///> Called when the polygon is complete + ///< Called when the polygon is complete virtual void OnComplete( const POLYGON_GEOM_MANAGER& aMgr ) = 0; virtual ~CLIENT() @@ -69,8 +68,8 @@ public: */ enum class LEADER_MODE { - DIRECT, ///> Unconstrained point-to-point - DEG45, ///> 45 Degree only + DIRECT, ///< Unconstrained point-to-point + DEG45, ///< 45 Degree only }; /** @@ -84,18 +83,17 @@ public: bool AddPoint( const VECTOR2I& aPt ); /** - * Mark the polygon finished and update the client + * Mark the polygon finished and update the client. */ void SetFinished(); /** - * Clear the manager state and start again + * Clear the manager state and start again. */ void Reset(); /** - * Set the leader mode to use when calculating the leader/returner - * lines + * Set the leader mode to use when calculating the leader/returner lines. */ void SetLeaderMode( LEADER_MODE aMode ); @@ -106,6 +104,7 @@ public: /** * Enables/disables self-intersecting polygons. + * * @param aEnabled true if self-intersecting polygons are enabled. */ void AllowIntersections( bool aEnabled ) @@ -114,7 +113,8 @@ public: } /** - * Checks whether self-intersecting polygons are enabled. + * Check whether self-intersecting polygons are enabled. + * * @return true if self-intersecting polygons are enabled. */ bool IntersectionsAllowed() const @@ -123,7 +123,8 @@ public: } /** - * Checks whether the locked points constitute a self-intersecting outline. + * Check whether the locked points constitute a self-intersecting outline. + * * @param aIncludeLeaderPts when true, also the leading points (not placed ones) will be tested. * @return True when the outline is self-intersecting. */ @@ -141,8 +142,7 @@ public: bool IsPolygonInProgress() const; /** - * @return true if locking in the given point would close the - * current polygon + * @return true if locking in the given point would close the current polygon. */ bool NewPointClosesOutline( const VECTOR2I& aPt ) const; @@ -183,19 +183,19 @@ private: void updateLeaderPoints( const VECTOR2I& aEndPoint, LEADER_MODE aModifier = LEADER_MODE::DIRECT ); - ///> The "user" of the polygon data that is informed when the geometry changes + ///< The "user" of the polygon data that is informed when the geometry changes CLIENT& m_client; - ///> The current mode of the leader line + ///< The current mode of the leader line LEADER_MODE m_leaderMode; - ///> Flag enabling self-intersecting polygons + ///< Flag enabling self-intersecting polygons bool m_intersectionsAllowed; - ///> Point that have been "locked in" + ///< Point that have been "locked in" SHAPE_LINE_CHAIN m_lockedPoints; - ///> Points in the temporary "leader" line(s) + ///< Points in the temporary "leader" line(s) SHAPE_LINE_CHAIN m_leaderPts; }; diff --git a/include/preview_items/polygon_item.h b/include/preview_items/polygon_item.h index b999037a59..ab24c5b949 100644 --- a/include/preview_items/polygon_item.h +++ b/include/preview_items/polygon_item.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KICAD, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -39,22 +39,17 @@ namespace PREVIEW { /** - * POLYGON_ITEM - * - * A preview item which shows an in-progress polygon, which - * can be used for zone outlines, etc + * A preview item which shows an in-progress polygon, which can be used for zone outlines, etc. */ class POLYGON_ITEM : public SIMPLE_OVERLAY_ITEM { public: - POLYGON_ITEM(); - ///> Gets the bounding box of the polygon + ///< Gets the bounding box of the polygon virtual const BOX2I ViewBBox() const override; - /** * Set the polygon points * @@ -66,14 +61,13 @@ public: const SHAPE_LINE_CHAIN& aLeaderPts ); private: - - ///> Draw rectangle and centre line onto GAL + ///< Draw rectangle and center line onto GAL void drawPreviewShape( KIGFX::VIEW* aView ) const override; - ///> complete polyline of locked in and leader points + ///< complete polyline of locked in and leader points SHAPE_LINE_CHAIN m_lockedChain, m_leaderChain; - ///> polygon fill + ///< polygon fill SHAPE_POLY_SET m_polyfill; static const double POLY_LINE_WIDTH; diff --git a/include/preview_items/ruler_item.h b/include/preview_items/ruler_item.h index 08c4c2ff8a..7c74edaef8 100644 --- a/include/preview_items/ruler_item.h +++ b/include/preview_items/ruler_item.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -36,8 +36,6 @@ namespace PREVIEW class TWO_POINT_GEOMETRY_MANAGER; /** - * RULER_ITEM - * * A drawn ruler item for showing the distance between two points. */ class RULER_ITEM : public EDA_ITEM @@ -45,13 +43,13 @@ class RULER_ITEM : public EDA_ITEM public: RULER_ITEM( const TWO_POINT_GEOMETRY_MANAGER& m_geomMgr, EDA_UNITS userUnits ); - ///> @copydoc EDA_ITEM::ViewBBox() + ///< @copydoc EDA_ITEM::ViewBBox() const BOX2I ViewBBox() const override; - ///> @copydoc EDA_ITEM::ViewGetLayers() + ///< @copydoc EDA_ITEM::ViewGetLayers() void ViewGetLayers( int aLayers[], int& aCount ) const override; - ///> @copydoc EDA_ITEM::ViewDraw(); + ///< @copydoc EDA_ITEM::ViewDraw(); void ViewDraw( int aLayer, KIGFX::VIEW* aView ) const override final; diff --git a/include/preview_items/selection_area.h b/include/preview_items/selection_area.h index 237bb9ae7a..4cf3e78c14 100644 --- a/include/preview_items/selection_area.h +++ b/include/preview_items/selection_area.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -36,12 +38,10 @@ namespace PREVIEW { /** - * SELECTION_AREA + * Represent a selection area (currently a rectangle) in a VIEW, drawn corner-to-corner between + * two points. * - * Represents a selection area (currently a rectangle) in a VIEW, - * drawn corner-to-corner between two points. This is useful when - * selecting a rectangular area, for lasso-select or zooming, for - * example. + * This is useful when selecting a rectangular area, for lasso-select or zooming, for example. */ class SELECTION_AREA : public SIMPLE_OVERLAY_ITEM { @@ -52,7 +52,7 @@ public: const BOX2I ViewBBox() const override; - ///> Set the origin of the rectange (the fixed corner) + ///< Set the origin of the rectangle (the fixed corner) void SetOrigin( VECTOR2I aOrigin ) { m_origin = aOrigin; diff --git a/include/preview_items/simple_overlay_item.h b/include/preview_items/simple_overlay_item.h index e95863c656..7beb7b3546 100644 --- a/include/preview_items/simple_overlay_item.h +++ b/include/preview_items/simple_overlay_item.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KICAD, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -58,13 +58,13 @@ public: SIMPLE_OVERLAY_ITEM(); /** - * Sets the overlay layer only. You can override this if + * Set the overlay layer only. You can override this if * you have more layers to draw on. */ void ViewGetLayers( int aLayers[], int& aCount ) const override; /** - * Draws the preview - this is done by calling the two functions: + * Draw the preview - this is done by calling the two functions: * setupGal() and drawPreviewShape(). If you need more than this, * or direct access to the VIEW, you probably should make a new *. @@ -87,19 +87,19 @@ public: return "SIMPLE_OVERLAY_ITEM"; } - ///> Set the stroke colour to set before drawing preview + ///< Set the stroke color to set before drawing preview void SetStrokeColor( const COLOR4D& aNewColor ) { m_strokeColor = aNewColor; } - ///> Set the fill colour to set before drawing preview + ///< Set the fill color to set before drawing preview void SetFillColor( const COLOR4D& aNewColor ) { m_fillColor = aNewColor; } - ///> Set the line width to set before drawing preview + ///< Set the line width to set before drawing preview void SetLineWidth( double aNewWidth ) { m_lineWidth = aNewWidth; @@ -110,15 +110,15 @@ private: /** * Set up the GAL canvas - this provides a default implementation, * that sets fill, stroke and width. + * * If that's not suitable, you can set more options in * updatePreviewShape(), but you might find that defining a new - * EDA_ITEM derivative is easier for heavily customised cases. + * EDA_ITEM derivative is easier for heavily customized cases. */ void setupGal( KIGFX::GAL& aGal ) const; /** - * Draw the preview onto the given GAL. setupGal() will be called - * before this function. + * Draw the preview onto the given GAL. setupGal() will be called before this function. * * Subclasses should implement this in terms of their own graphical * data. diff --git a/include/preview_items/two_point_geom_manager.h b/include/preview_items/two_point_geom_manager.h index eb87f82e7a..775d18b348 100644 --- a/include/preview_items/two_point_geom_manager.h +++ b/include/preview_items/two_point_geom_manager.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,16 +35,13 @@ namespace PREVIEW { /** - * TWO_POINT_GEOMETRY_MANAGER - * - * Represents a very simple geometry manager for items that have - * a start and end point. + * Represent a very simple geometry manager for items that have a start and end point. */ class TWO_POINT_GEOMETRY_MANAGER { public: - ///> Set the origin of the ruler (the fixed end) + ///< Set the origin of the ruler (the fixed end) void SetOrigin( const VECTOR2I& aOrigin ) { m_origin = aOrigin; @@ -58,8 +55,7 @@ public: } /** - * Set the current end of the rectangle (the end that moves - * with the cursor. + * Set the current end of the rectangle (the end that moves with the cursor. */ void SetEnd( const VECTOR2I& aEnd ) { @@ -107,8 +103,7 @@ public: } /** - * @return true if the geoemtry has changed, eg such that a client - * should redraw + * @return true if the geometry has changed, eg such that a client should redraw. */ bool HasGeometryChanged() const { @@ -116,8 +111,8 @@ public: } /** - * Clear the geometry changed flag, call after the client code has - * updated everything as needed. + * Clear the geometry changed flag, call after the client code has updated everything as + * needed. */ void ClearGeometryChanged() { @@ -125,7 +120,7 @@ public: } protected: - ///> Mark the geometry as changed for clients to notice + ///< Mark the geometry as changed for clients to notice void setGeometryChanged() { m_changed = true; @@ -136,7 +131,7 @@ private: VECTOR2I m_origin, m_end; bool m_angleSnap = false; - ///> Has the gemotry changed such that a client should redraw? + ///< Has the geometry changed such that a client should redraw? bool m_changed = false; bool m_originSet = false; }; diff --git a/include/project.h b/include/project.h index bfb700c797..2f87130ec3 100644 --- a/include/project.h +++ b/include/project.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2014-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2014-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -56,7 +56,7 @@ class PROJECT_LOCAL_SETTINGS; /** * Container for project specific data. * - * Because it is in the neutral program top, which is not linked to by subsidiarly DSOs, + * Because it is in the neutral program top, which is not linked to by subsidiary DSOs, * any functions in this interface must be virtual. */ class PROJECT @@ -67,7 +67,7 @@ public: * * Derive #PROJECT elements from this, it has a virtual destructor, and Elem*() functions * can work with it. Implementation is opaque in class #PROJECT. If find you have to - * include derived class headersin this file, you are doing incompatible with the goal + * include derived class headers in this file, you are doing incompatible with the goal * of this class. Keep knowledge of derived classes opaque to class PROJECT please. */ class _ELEM @@ -180,10 +180,10 @@ public: * Return a "retained string", which is any session and project specific string * identified in enum #RSTRING_T. * - *Retained strings are not written to disk, and are therefore good only for the current + * Retained strings are not written to disk, and are therefore good only for the current * session. */ - virtual const wxString& GetRString( RSTRING_T aStringId ); + virtual const wxString& GetRString( RSTRING_T aStringId ); /** * Store a "retained string", which is any session and project specific string @@ -192,7 +192,7 @@ public: * Retained strings are not written to disk, and are therefore good only for the current * session. */ - virtual void SetRString( RSTRING_T aStringId, const wxString& aString ); + virtual void SetRString( RSTRING_T aStringId, const wxString& aString ); /** * The set of #_ELEMs that a #PROJECT can hold. @@ -255,7 +255,7 @@ public: virtual FP_LIB_TABLE* PcbFootprintLibs( KIWAY& aKiway ); // These are the non-virtual DATA LOAD ON DEMAND members. They load project related - // data on demand, and do so typicallly into m_elems[] at a particular index using + // data on demand, and do so typically into m_elems[] at a particular index using // SetElem() & GetElem(). That is, they wrap SetElem() and GetElem(). // To get the data to reload on demand, first SetProjectFullName(), // then call SetElem( ELEM_T, NULL ) from client code. @@ -342,7 +342,7 @@ private: wxFileName m_project_name; ///< \/\.pro wxString m_pro_date_and_time; - ///> True if the project is read-only: no project files will be written + ///< True if the project is read-only: no project files will be written bool m_readOnly; /// Backing store for project data -- owned by SETTINGS_MANAGER diff --git a/include/project/board_project_settings.h b/include/project/board_project_settings.h index 2328f178a8..25d7e9e551 100644 --- a/include/project/board_project_settings.h +++ b/include/project/board_project_settings.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 Jon Evans - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -83,16 +83,16 @@ struct SELECTION_FILTER_OPTIONS }; /** - * Determines how inactive layers should be displayed + * Determine how inactive layers should be displayed. */ enum class HIGH_CONTRAST_MODE { - NORMAL = 0, ///> Non-active layers are shown normally (no high-contrast mode) - DIMMED, ///> Non-active layers are dimmed (old high-contrast mode) - HIDDEN ///> Non-active layers are hidden + NORMAL = 0, ///< Non-active layers are shown normally (no high-contrast mode) + DIMMED, ///< Non-active layers are dimmed (old high-contrast mode) + HIDDEN ///< Non-active layers are hidden }; -///> Determines how zones should be displayed +///< Determine how zones should be displayed. enum class ZONE_DISPLAY_MODE { SHOW_FILLED, ///< Filled polygons are shown @@ -100,7 +100,7 @@ enum class ZONE_DISPLAY_MODE SHOW_FILLED_OUTLINE ///< Outlines of filled polygons are shown }; -///> Determines how net color overrides should be applied +///< Determine how net color overrides should be applied. enum class NET_COLOR_MODE { OFF, ///< Net (and netclass) colors are not shown @@ -108,7 +108,7 @@ enum class NET_COLOR_MODE ALL ///< Net/netclass colors are shown on all net copper }; -///> Determines how ratsnest lines are drawn +///< Determine how ratsnest lines are drawn. enum class RATSNEST_MODE { ALL, ///< Ratsnest lines are drawn to items on all layers (default) @@ -116,7 +116,7 @@ enum class RATSNEST_MODE }; /** - * A saved set of layers that are visible + * A saved set of layers that are visible. */ struct LAYER_PRESET { diff --git a/include/property.h b/include/property.h index ea178bed2c..17e191d656 100644 --- a/include/property.h +++ b/include/property.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -43,7 +44,7 @@ class PROPERTY_BASE; template class ENUM_MAP; -///> Common property types +///< Common property types enum PROPERTY_DISPLAY { DEFAULT, ///< Default property for a given type @@ -52,7 +53,7 @@ enum PROPERTY_DISPLAY DECIDEGREE ///< Convert decidegrees to degrees for display }; -///> Macro to generate unique identifier for a type +///< Macro to generate unique identifier for a type #define TYPE_HASH( x ) typeid( x ).hash_code() #define TYPE_NAME( x ) typeid( x ).name() //#define TYPE_HASH( x ) typeid( std::decay::type ).hash_code() @@ -169,7 +170,7 @@ public: class PROPERTY_BASE { private: - ///> Used to generate unique IDs. Must come up front so it's initialized before ctor. + ///< Used to generate unique IDs. Must come up front so it's initialized before ctor. public: PROPERTY_BASE( const wxString& aName, PROPERTY_DISPLAY aDisplay = DEFAULT ) : @@ -189,7 +190,7 @@ public: } /** - * Returns a limited set of possible values (e.g. enum). Check with HasChoices() if a particular + * Return a limited set of possible values (e.g. enum). Check with HasChoices() if a particular * PROPERTY provides such set. */ virtual const wxPGChoices& Choices() const @@ -199,7 +200,7 @@ public: } /** - * Sets the possible values for for the property. + * Set the possible values for for the property. */ virtual void SetChoices( const wxPGChoices& aChoices ) { @@ -207,7 +208,7 @@ public: } /** - * Returns true if this PROPERTY has a limited set of possible values. + * Return true if this PROPERTY has a limited set of possible values. * @see PROPERTY_BASE::Choices() */ virtual bool HasChoices() const @@ -216,7 +217,7 @@ public: } /** - * Returns true if aObject offers this PROPERTY. + * Return true if aObject offers this PROPERTY. */ bool Available( INSPECTABLE* aObject ) const { @@ -224,7 +225,7 @@ public: } /** - * Sets a callback function to determine whether an object provides this property. + * Set a callback function to determine whether an object provides this property. */ void SetAvailableFunc( std::function aFunc ) { @@ -232,17 +233,17 @@ public: } /** - * Returns type-id of the Owner class. + * Return type-id of the Owner class. */ virtual size_t OwnerHash() const = 0; /** - * Returns type-id of the Base class. + * Return type-id of the Base class. */ virtual size_t BaseHash() const = 0; /** - * Returns type-id of the property type. + * Return type-id of the property type. */ virtual size_t TypeHash() const = 0; @@ -279,7 +280,7 @@ private: const wxString m_name; const PROPERTY_DISPLAY m_display; - std::function m_availFunc; ///> Eval to determine if prop is available + std::function m_availFunc; ///< Eval to determine if prop is available friend class INSPECTABLE; }; @@ -360,19 +361,19 @@ protected: return res; } - ///> Set method + ///< Set method std::unique_ptr> m_setter; - ///> Get method + ///< Get method std::unique_ptr> m_getter; - ///> Owner class type-id + ///< Owner class type-id const size_t m_ownerHash; - ///> Base class type-id + ///< Base class type-id const size_t m_baseHash; - ///> Property value type-id + ///< Property value type-id const size_t m_typeHash; }; @@ -596,7 +597,7 @@ private: DECLARE_ENUM_TO_WXANY( type ) \ IMPLEMENT_ENUM_TO_WXANY( type ) -///> Macro to define read-only fields (no setter method available) +///< Macro to define read-only fields (no setter method available) #define NO_SETTER( owner, type ) ( ( void ( owner::* )( type ) ) nullptr ) /* diff --git a/include/property_mgr.h b/include/property_mgr.h index b17b146aa0..f13f0b6e72 100644 --- a/include/property_mgr.h +++ b/include/property_mgr.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -37,7 +39,7 @@ class PROPERTY_BASE; class TYPE_CAST_BASE; -///> Unique type identifier +///< Unique type identifier using TYPE_ID = size_t; using PROPERTY_LIST = std::vector; @@ -45,7 +47,7 @@ using PROPERTY_LIST = std::vector; using PROPERTY_SET = std::set>; /** - * Provides class metadata. Each class handled by PROPERTY_MANAGER + * Provide class metadata. Each class handled by PROPERTY_MANAGER * needs to be described using AddProperty(), AddTypeCast() and InheritsAfter() methods. * * Enum types use a dedicated property type (PROPERTY_ENUM), define its possible values @@ -68,9 +70,9 @@ public: } /** - * Associates a name with a type. + * Associate a name with a type. * - * Builds a map to provide faster type look-up. + * Build a map to provide faster type look-up. * * @param aType is the type identifier (obtained using TYPE_HASH()). * @param aName is the type name. @@ -78,7 +80,7 @@ public: void RegisterType( TYPE_ID aType, const wxString& aName ); /** - * Returns name of a type. + * Return name of a type. * * @param aType is the type identifier (obtained using TYPE_HASH()). * @return Name of the type or empty string, if not available. @@ -86,7 +88,7 @@ public: const wxString& ResolveType( TYPE_ID aType ) const; /** - * Returns a property for a specific type. + * Return a property for a specific type. * * @param aType is the type identifier (obtained using TYPE_HASH()). * @param aProperty is the property name used during class registration. @@ -95,7 +97,7 @@ public: PROPERTY_BASE* GetProperty( TYPE_ID aType, const wxString& aProperty ) const; /** - * Returns all properties for a specific type. + * Return all properties for a specific type. * * @param aType is the type identifier (obtained using TYPE_HASH()). * @return Vector storing all properties of the requested type. @@ -103,7 +105,7 @@ public: const PROPERTY_LIST& GetProperties( TYPE_ID aType ) const; /** - * Casts a type to another type. Used for correct type-casting of types with + * Cast a type to another type. Used for correct type-casting of types with * multi-inheritance. Requires registration of an appropriate converter (AddTypeCast). * * @param aSource is a pointer to the casted object. @@ -121,14 +123,14 @@ public: } /** - * Registers a property. + * Register a property. * * @param aProperty is the property to register. */ void AddProperty( PROPERTY_BASE* aProperty ); /** - * Replaces an existing property for a specific type. + * Replace an existing property for a specific type. * * It is used to modify a property that has been inherited from a base class. * This method is used instead of AddProperty(). @@ -140,14 +142,14 @@ public: void ReplaceProperty( size_t aBase, const wxString& aName, PROPERTY_BASE* aNew ); /** - * Registers a type converter. Required prior TypeCast() usage. + * Register a type converter. Required prior TypeCast() usage. * * @param aCast is the type converter to register. */ void AddTypeCast( TYPE_CAST_BASE* aCast ); /** - * Declares an inheritance relationship between types. + * Declare an inheritance relationship between types. * * @param aBase is the base type identifier (obtained using TYPE_HASH()). * @param aDerived is the derived type identifier (obtained using TYPE_HASH()). @@ -155,7 +157,7 @@ public: void InheritsAfter( TYPE_ID aDerived, TYPE_ID aBase ); /** - * Returns true if aDerived is inherited from aBase. + * Return true if aDerived is inherited from aBase. */ bool IsOfType( TYPE_ID aDerived, TYPE_ID aBase ) const; @@ -170,7 +172,7 @@ public: } /** - * Rebuilds the list of all registered properties. Needs to be called + * Rebuild the list of all registered properties. Needs to be called * once before GetProperty()/GetProperties() are used. */ void Rebuild(); @@ -194,7 +196,7 @@ private: { } - ///> Structure holding type meta-data + ///< Structure holding type meta-data struct CLASS_DESC { CLASS_DESC( TYPE_ID aId ) @@ -202,38 +204,38 @@ private: { } - ///> Unique type identifier (obtained using TYPE_HASH) + ///< Unique type identifier (obtained using TYPE_HASH) const TYPE_ID m_id; - ///> Types after which this type inherits + ///< Types after which this type inherits std::vector> m_bases; - ///> Properties unique to this type (i.e. not inherited) + ///< Properties unique to this type (i.e. not inherited) std::map> m_ownProperties; - ///> Type converters available for this type + ///< Type converters available for this type std::map> m_typeCasts; - ///> All properties (both unique to the type and inherited) + ///< All properties (both unique to the type and inherited) std::vector m_allProperties; - ///> Replaced properties (TYPE_ID / name) + ///< Replaced properties (TYPE_ID / name) PROPERTY_SET m_replaced; - ///> Recreates the list of properties + ///< Recreates the list of properties void rebuild(); - ///> Traverses the class inheritance hierarchy bottom-to-top, gathering - ///> all properties available to a type + ///< Traverses the class inheritance hierarchy bottom-to-top, gathering + ///< all properties available to a type void collectPropsRecur( PROPERTY_LIST& aResult, PROPERTY_SET& aReplaced ) const; }; - ///> Returns metadata for a specific type + ///< Returns metadata for a specific type CLASS_DESC& getClass( TYPE_ID aTypeId ); std::unordered_map m_classNames; - ///> Map of all available types + ///< Map of all available types std::unordered_map m_classes; /// Flag indicating that the list of properties needs to be rebuild (RebuildProperties()) @@ -243,7 +245,7 @@ private: }; -///> Helper macro to map type hashes to names +///< Helper macro to map type hashes to names #define REGISTER_TYPE(x) PROPERTY_MANAGER::Instance().RegisterType(TYPE_HASH(x), TYPE_NAME(x)) #endif /* PROPERTY_MGR_H */ diff --git a/include/status_popup.h b/include/status_popup.h index 8a05814921..62f0f12c81 100644 --- a/include/status_popup.h +++ b/include/status_popup.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014-2015 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * Author: Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -49,7 +49,7 @@ public: virtual void Popup( wxWindow* aFocus = nullptr ); virtual void PopupFor( int aMsecs ); - virtual void Move( const wxPoint &aWhere ); + virtual void Move( const wxPoint& aWhere ); virtual void Move( const VECTOR2I& aWhere ); /** @@ -64,7 +64,7 @@ protected: void onCharHook( wxKeyEvent& aEvent ); - ///> Expire timer even handler + ///< Expire timer even handler void onExpire( wxTimerEvent& aEvent ); wxPanel* m_panel; diff --git a/include/validators.h b/include/validators.h index 013b98b3ad..719bbf9fe3 100644 --- a/include/validators.h +++ b/include/validators.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 Wayne Stambaugh - * Copyright (C) 2004-2019 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2004-2021 KiCad Developers, see change_log.txt for contributors. * Copyright (C) 2018 CERN * * This program is free software; you can redistribute it and/or @@ -150,16 +150,16 @@ public: bool Validate( wxWindow* aParent ) override; protected: - ///> Compiles and stores a regular expression + ///< Compiles and stores a regular expression void compileRegEx( const wxString& aRegEx, int aFlags ); - ///> Original regular expression (for copy constructor) + ///< Original regular expression (for copy constructor) wxString m_regExString; - ///> Original compilation flags (for copy constructor) + ///< Original compilation flags (for copy constructor) int m_regExFlags; - ///> Compiled regex + ///< Compiled regex wxRegEx m_regEx; }; diff --git a/include/widgets/bitmap_button.h b/include/widgets/bitmap_button.h index c578b5da8b..4ff0ed9eca 100644 --- a/include/widgets/bitmap_button.h +++ b/include/widgets/bitmap_button.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2020 Ian McInerney - * Copyright (C) 2020 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -102,19 +102,19 @@ protected: } private: - ///> Bitmap shown when button is enabled + ///< Bitmap shown when button is enabled wxBitmap m_normalBitmap; - ///> Bitmap shown when button is disabled + ///< Bitmap shown when button is disabled wxBitmap m_disabledBitmap; - ///> Current state of the button + ///< Current state of the button int m_buttonState; - ///> Padding on each side of the bitmap + ///< Padding on each side of the bitmap int m_padding; - ///> Size without the padding + ///< Size without the padding wxSize m_unadjustedMinSize; }; diff --git a/include/widgets/bitmap_toggle.h b/include/widgets/bitmap_toggle.h index 9866df16e7..26c6d2619f 100644 --- a/include/widgets/bitmap_toggle.h +++ b/include/widgets/bitmap_toggle.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Jon Evans * * This program is free software; you can redistribute it and/or @@ -43,13 +43,13 @@ class BITMAP_TOGGLE : public wxPanel public: BITMAP_TOGGLE() {} - BITMAP_TOGGLE( wxWindow *aParent, wxWindowID aId, const wxBitmap& aCheckedBitmap, + BITMAP_TOGGLE( wxWindow* aParent, wxWindowID aId, const wxBitmap& aCheckedBitmap, const wxBitmap& aUncheckedBitmap, bool aChecked = false ); - ///> Set the checkbox state + ///< Set the checkbox state void SetValue( bool aValue ); - ///> Read the checkbox state + ///< Read the checkbox state bool GetValue() const { return m_checked; } private: @@ -57,10 +57,10 @@ private: wxStaticBitmap* m_bitmap; - ///> Bitmap to display in unchecked state + ///< Bitmap to display in unchecked state wxBitmap m_unchecked_bitmap; - ///> Bitmap to display in checked state + ///< Bitmap to display in checked state wxBitmap m_checked_bitmap; }; diff --git a/include/widgets/gal_options_panel.h b/include/widgets/gal_options_panel.h index 28cd329175..11db79aaa9 100644 --- a/include/widgets/gal_options_panel.h +++ b/include/widgets/gal_options_panel.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -50,7 +50,6 @@ public: bool TransferDataFromWindow() override; private: - wxBoxSizer* m_mainSizer; wxRadioBox* m_gridStyle; @@ -70,7 +69,7 @@ private: wxRadioBox* m_cursorShape; wxCheckBox* m_forceCursorDisplay; - ///> The GAL options to read/write + ///< The GAL options to read/write KIGFX::GAL_DISPLAY_OPTIONS& m_galOptions; }; diff --git a/include/widgets/indicator_icon.h b/include/widgets/indicator_icon.h index b4c47c1b0a..63c8febcf9 100644 --- a/include/widgets/indicator_icon.h +++ b/include/widgets/indicator_icon.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017-2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -53,7 +53,7 @@ public: virtual ~ICON_PROVIDER() {}; /** - * Gets a reference to the row icon in the given mode + * Get a reference to the row icon in the given mode. * * @param aIconId the id of the icon to get (depends on the * provider). @@ -63,7 +63,7 @@ public: /** * Accessor for the default icon providers, which take - * true and false for IDs, meaining on/off. + * true and false for IDs, meaning on/off. * * @param aAlternative false for blue arrow/blank, true for the * green diamond @@ -82,7 +82,7 @@ public: ICON_ID aInitialIcon, int aID ); /** - * Sets the row indiciator to the given state + * Set the row indicator to the given state. * * @param aIconId the icon ID to pass to the provider. */ @@ -96,34 +96,33 @@ public: private: - ///> An class that delivers icons for the indictor (currently just - ///> uses a default implementation). + ///< An class that delivers icons for the indicator (currently just + ///< uses a default implementation). ICON_PROVIDER& m_iconProvider; - ///> Handle on the bitmap widget + ///< Handle on the bitmap widget wxStaticBitmap* m_bitmap; - ///> Is the icon currently "on" + ///< Is the icon currently "on" ICON_ID m_currentId; }; /** - * Icon provider for the "standard" row indicators, for example in - * layer selection lists + * Icon provider for the "standard" row indicators, for example in layer selection lists */ class ROW_ICON_PROVIDER: public INDICATOR_ICON::ICON_PROVIDER { public: - ///> State constants to select the right icons + ///< State constants to select the right icons enum STATE { - OFF, ///> Row "off" or "deselected" - DIMMED, ///> Row "dimmed" - ON, ///> Row "on" or "selected" - UP, ///> Row above design alpha - DOWN, ///> Row below design alpha + OFF, ///< Row "off" or "deselected" + DIMMED, ///< Row "dimmed" + ON, ///< Row "on" or "selected" + UP, ///< Row above design alpha + DOWN, ///< Row below design alpha }; /** @@ -132,7 +131,7 @@ public: */ ROW_ICON_PROVIDER( int aSize ); - ///> @copydoc INDICATOR_ICON::ICON_PROVIDER::GetIndicatorIcon() + ///< @copydoc INDICATOR_ICON::ICON_PROVIDER::GetIndicatorIcon() const wxBitmap& GetIndicatorIcon( INDICATOR_ICON::ICON_ID aIconId ) const override; private: @@ -144,5 +143,4 @@ private: }; - #endif // ROW_INDICATOR__H_ diff --git a/include/widgets/lib_tree.h b/include/widgets/lib_tree.h index 5a5dff2d44..814c916224 100644 --- a/include/widgets/lib_tree.h +++ b/include/widgets/lib_tree.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 Henner Zeller - * Copyright (C) 2014-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2014-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -42,7 +42,7 @@ class LIB_TABLE; class LIB_TREE : public wxPanel { public: - ///> Flags to select extra widgets + ///< Flags to select extra widgets enum WIDGETS { NONE = 0x00, SEARCH = 0x01, DETAILS = 0x02, ALL = 0xFF }; /** @@ -80,7 +80,7 @@ public: void SelectLibId( const LIB_ID& aLibId ); /** - * Ensure that an item is visible (preferrably centered). + * Ensure that an item is visible (preferably centered). */ void CenterLibId( const LIB_ID& aLibId ); @@ -95,7 +95,7 @@ public: void ExpandLibId( const LIB_ID& aLibId ); /** - * Regenerates the tree. + * Regenerate the tree. */ void Regenerate( bool aKeepState ); @@ -108,7 +108,7 @@ public: protected: /** - * Expands or collapses a node, switching it to the opposite state. + * Expand or collapse a node, switching it to the opposite state. */ void toggleExpand( const wxDataViewItem& aTreeId ); @@ -137,21 +137,21 @@ protected: */ struct STATE { - ///> List of expanded nodes + ///< List of expanded nodes std::vector expanded; std::vector pinned; - ///> Current selection, might be not valid if nothing was selected + ///< Current selection, might be not valid if nothing was selected LIB_ID selection; }; /** - * Returns the component tree widget state. + * Return the component tree widget state. */ STATE getState() const; /** - * Restores the component tree widget state from an object. + * Restore the component tree widget state from an object. */ void setState( const STATE& aState ); @@ -176,10 +176,10 @@ protected: wxHtmlWindow* m_details_ctrl; }; -///> Custom event sent when a new component is preselected +///< Custom event sent when a new component is preselected wxDECLARE_EVENT( COMPONENT_PRESELECTED, wxCommandEvent ); -///> Custom event sent when a component is selected +///< Custom event sent when a component is selected wxDECLARE_EVENT( COMPONENT_SELECTED, wxCommandEvent ); #endif /* LIB_TREE_H */ diff --git a/include/widgets/text_ctrl_eval.h b/include/widgets/text_ctrl_eval.h index edb0b85973..eb266f3dc4 100644 --- a/include/widgets/text_ctrl_eval.h +++ b/include/widgets/text_ctrl_eval.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017-2018 CERN + * Copyright (C) 2017-2021 CERN * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -39,24 +39,24 @@ class TEXT_CTRL_EVAL : public wxTextCtrl { public: TEXT_CTRL_EVAL( wxWindow* aParent, wxWindowID aId, const wxString& aValue = wxEmptyString, - const wxPoint& aPos = wxDefaultPosition, const wxSize& aSize = wxDefaultSize, - long aStyle = 0, const wxValidator& aValidator = wxDefaultValidator, - const wxString& aName = wxTextCtrlNameStr ); + const wxPoint& aPos = wxDefaultPosition, const wxSize& aSize = wxDefaultSize, + long aStyle = 0, const wxValidator& aValidator = wxDefaultValidator, + const wxString& aName = wxTextCtrlNameStr ); virtual ~TEXT_CTRL_EVAL() { } /** - * Set a new value in evaluator buffer, and display it - * in the wxTextCtrl. + * Set a new value in evaluator buffer, and display it in the wxTextCtrl. + * * @param aValue is the new value to store and display * if aValue is empty, the value "0" is stored and displayed */ void SetValue( const wxString& aValue ) override; protected: - ///> Numeric expression evaluator + ///< Numeric expression evaluator NUMERIC_EVALUATOR m_eval; void onTextFocusGet( wxFocusEvent& aEvent ); diff --git a/include/widgets/unit_binder.h b/include/widgets/unit_binder.h index c99449a9dd..4e166d2b05 100644 --- a/include/widgets/unit_binder.h +++ b/include/widgets/unit_binder.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014-2015 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * Author: Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -43,7 +43,6 @@ class UNIT_BINDER : public wxEvtHandler public: /** - * Constructor. * @param aParent is the parent EDA_DRAW_FRAME. * @param aLabel is the static text used to label the text input widget (note: the label * text, trimmed of its colon, will also be used in error messages) @@ -81,8 +80,8 @@ public: void SetDataType( EDA_DATA_TYPE aDataType ); /** - * Function SetValue - * Sets new value (in Internal Units) for the text field, taking care of units conversion. + * Set new value (in Internal Units) for the text field, taking care of units conversion. + * * @param aValue is the new value. */ virtual void SetValue( int aValue ); @@ -90,8 +89,8 @@ public: void SetValue( wxString aValue ); /** - * Function SetDoubleValue - * Sets new value (in Internal Units) for the text field, taking care of units conversion. + * Set new value (in Internal Units) for the text field, taking care of units conversion. + * * @param aValue is the new value. * the initialized value will be truncated according to the precision set by SetPrecision() * (if not <= 0) @@ -99,9 +98,9 @@ public: virtual void SetDoubleValue( double aValue ); /** - * Function ChangeValue - * Changes the value (in Internal Units) for the text field, taking care of units conversion + * Change the value (in Internal Units) for the text field, taking care of units conversion * but does not trigger the update routine + * * @param aValue is the new value. */ virtual void ChangeValue( int aValue ); @@ -109,36 +108,32 @@ public: void ChangeValue( const wxString& aValue ); /** - * Function GetValue - * Returns the current value in Internal Units. + * Return the current value in Internal Units. */ virtual long long int GetValue(); /** - * Function GetValue - * Returns the current value in Internal Units. - * the returned value will be truncated according to the precision set by + * Return the current value in Internal Units. + * + * The returned value will be truncated according to the precision set by * SetPrecision() (if not <= 0) */ virtual double GetDoubleValue(); /** - * Function IsIndeterminate - * Returns true if the control holds the indeterminate value (for instance, if it + * Return true if the control holds the indeterminate value (for instance, if it * represents a multiple selection of differing values). */ bool IsIndeterminate() const; /** - * Function GetOriginalText - * Returns the pre-evaluated text (or the current text if evaluation is not supported). + * Return the pre-evaluated text (or the current text if evaluation is not supported). * Used primarily to remember values between dialog invocations. */ wxString GetOriginalText() const; /** - * Function Validate - * Validates the control against the given range, informing the user of any errors found. + * Validate the control against the given range, informing the user of any errors found. * * @param aMin a minimum value for validation * @param aMax a maximum value for validation @@ -150,14 +145,12 @@ public: void SetLabel( const wxString& aLabel ); /** - * Function Enable - * Enables/diasables the label, widget and units label. + * Enable/disable the label, widget and units label. */ void Enable( bool aEnable ); /** - * Function Show - * Shows/hides the label, widget and units label. + * Show/hide the label, widget and units label. * * @param aShow called for the Show() routine in wx * @param aResize if true, the element will be sized to 0 on hide and -1 on show @@ -175,8 +168,7 @@ public: } /** - * Function SetOriginTransform - * Sets the current origin transform mode + * Set the current origin transform mode */ void SetCoordType( ORIGIN_TRANSFORMS::COORD_TYPES_T aCoordType ) { @@ -191,10 +183,12 @@ protected: void onUnitsChanged( wxCommandEvent& aEvent ); - /** When m_precision > 0 truncate the value aValue to show only + /** + * When m_precision > 0 truncate the value aValue to show only * m_precision digits in mantissa. * used in GetDoubleValue to return a rounded value. * Mainly for units set to DEGREES. + * * @param aValue is the value to modify. * @param aValueUsesUserUnits must be set to true if aValue is a user value, * and set to false if aValue is a internal unit value. @@ -204,25 +198,25 @@ protected: EDA_DRAW_FRAME* m_frame; - ///> The bound widgets + ///< The bound widgets wxStaticText* m_label; wxWindow* m_valueCtrl; wxStaticText* m_unitLabel; // Can be nullptr - ///> Currently used units. + ///< Currently used units. EDA_UNITS m_units; EDA_DATA_TYPE m_dataType; int m_precision; // 0 to 6 - ///> Validation support. + ///< Validation support. wxString m_errorMessage; - ///> Evaluator + ///< Evaluator NUMERIC_EVALUATOR m_eval; bool m_allowEval; bool m_needsEval; - ///> Selection start and end of the original text + ///< Selection start and end of the original text long m_selStart; long m_selEnd; diff --git a/include/widgets/wx_busy_indicator.h b/include/widgets/wx_busy_indicator.h index dcc9fc3285..017c15ed99 100644 --- a/include/widgets/wx_busy_indicator.h +++ b/include/widgets/wx_busy_indicator.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see CHANGELOG.TXT for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see CHANGELOG.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -45,8 +45,8 @@ public: WX_BUSY_INDICATOR(); private: - ///> This is the actual WX cursor that is the indicator. + ///< This is the actual WX cursor that is the indicator. std::unique_ptr m_cursor; }; -#endif // COMMON_WIDGETS_WX_BUSY_INDICATOR__H \ No newline at end of file +#endif // COMMON_WIDGETS_WX_BUSY_INDICATOR__H diff --git a/libs/kimath/include/bezier_curves.h b/libs/kimath/include/bezier_curves.h index bf6aee3d49..81701fbde4 100644 --- a/libs/kimath/include/bezier_curves.h +++ b/libs/kimath/include/bezier_curves.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2014-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2014-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -30,6 +30,7 @@ /** * Bezier curves to polygon converter. + * * Only quadratic and cubic Bezier curves are handled */ class BEZIER_POLY @@ -44,9 +45,10 @@ public: } /** - * Converts Bezier curve to a polygon. + * Convert a Bezier curve to a polygon. + * * @param aOutput will be used as an output vector storing polygon points. - * @param aMinSegLen is the min dist between 2 successve points. + * @param aMinSegLen is the min dist between 2 successive points. * It can be used to reduce the number of points. * (the last point is always generated) */ @@ -56,7 +58,7 @@ public: private: double m_minSegLen; - ///> Control points + ///< Control points std::vector m_ctrlPts; }; diff --git a/libs/kimath/include/geometry/direction45.h b/libs/kimath/include/geometry/direction45.h index 5c3785519c..6aaca9b447 100644 --- a/libs/kimath/include/geometry/direction45.h +++ b/libs/kimath/include/geometry/direction45.h @@ -2,8 +2,9 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2015 CERN - * Author: Tomasz Wlostowski - * Copyright (C) 2017-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. + * + * @author Tomasz Wlostowski * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -30,18 +31,18 @@ #undef Opposite /** - * DIRECTION_45. - * Represents route directions & corner angles in a 45-degree metric. + * Represent route directions & corner angles in a 45-degree metric. */ - class DIRECTION_45 { public: /** - * Represents available directions - there are 8 of them, as on a rectilinear map (north = up) + - * an extra undefined direction, reserved for traces that don't respect 45-degree routing regime. - * NOTE: North represents "up" to the user looking at the application, which is the negative-y + * Available directions, there are 8 of them, as on a rectilinear map (north = up) + + * an extra undefined direction, reserved for traces that don't respect 45-degree routing + * regime. + * + * @note North represents "up" to the user looking at the application, which is the negative-y * direction in the world coordinate space! */ enum Directions : int @@ -59,8 +60,7 @@ public: }; /** - * Enum AngleType - * Represents kind of angle formed by vectors heading in two DIRECTION_45s. + * Represent kind of angle formed by vectors heading in two DIRECTION_45s. */ enum AngleType { @@ -75,7 +75,6 @@ public: DIRECTION_45( Directions aDir = UNDEFINED ) : m_dir( aDir ), m_90deg( false ) {} /** - * Constructor * @param aVec vector in world space, whose direction will be translated into a DIRECTION_45. */ DIRECTION_45( const VECTOR2I &aVec, bool a90 = false ) : @@ -87,7 +86,6 @@ public: } /** - * Constructor * @param aSeg segment, whose direction will be translated into a DIRECTION_45. */ DIRECTION_45( const SEG& aSeg, bool a90 = false ) : @@ -99,7 +97,8 @@ public: } /** - * Creates a DIRECTION_45 from the endpoints of a given arc + * Create a DIRECTION_45 from the endpoints of a given arc. + * * @param aArc will be translated into the closest DIRECTION_45 */ DIRECTION_45( const SHAPE_ARC& aArc, bool a90 = false ) : @@ -111,8 +110,8 @@ public: } /** - * Function Format() - * Formats the direction in a human readable word. + * Format the direction in a human readable word. + * * @return name of the direction */ const std::string Format() const @@ -152,8 +151,8 @@ public: } /** - * Function Opposite() - * Returns a direction opposite (180 degree) to (this) + * Return a direction opposite (180 degree) to (this). + * * @return opposite direction */ DIRECTION_45 Opposite() const @@ -163,8 +162,8 @@ public: } /** - * Function Angle() - * Returns the type of angle between directions (this) and aOther. + * Return the type of angle between directions (this) and \a aOther. + * * @param aOther direction to compare angle with */ AngleType Angle( const DIRECTION_45& aOther ) const @@ -187,8 +186,7 @@ public: } /** - * Function IsObtuse() - * @return true, when (this) forms an obtuse angle with aOther + * @return true, when (this) forms an obtuse angle with \a aOther. */ bool IsObtuse( const DIRECTION_45& aOther ) const { @@ -196,8 +194,8 @@ public: } /** - * Function IsDiagonal() - * Returns true if the direction is diagonal (e.g. North-West, South-East, etc) + * Returns true if the direction is diagonal (e.g. North-West, South-East, etc). + * * @return true, when diagonal. */ bool IsDiagonal() const @@ -211,8 +209,9 @@ public: } /** - * Builds a 2-segment line chain between points aP0 and aP1 and following 45-degree routing + * Build a 2-segment line chain between points aP0 and aP1 and following 45-degree routing * regime. If aStartDiagonal is true, the trace starts with a diagonal segment. + * * @param aP0 starting point * @param aP1 ending point * @param aStartDiagonal whether the first segment has to be diagonal @@ -234,10 +233,7 @@ public: } /** - * Function Right() - * - * Returns the direction on the right side of this (i.e. turns right - * by 45 or 90 deg) + * Return the direction on the right side of this (i.e. turns right by 45 or 90 deg). */ const DIRECTION_45 Right() const { @@ -255,10 +251,7 @@ public: } /** - * Function Left() - * - * Returns the direction on the left side of this (i.e. turns left - * by 45 or 90 deg) + * Return the direction on the left side of this (i.e. turns left by 45 or 90 deg). */ const DIRECTION_45 Left() const { @@ -304,9 +297,9 @@ public: private: /** - * Function construct() - * Calculates the direction from a vector. If the vector's angle is not a multiple of 45 + * Calculate the direction from a vector. If the vector's angle is not a multiple of 45 * degrees, the direction is rounded to the nearest octant. + * * @param aVec our vector */ void construct_( const VECTOR2I& aVec ) @@ -337,10 +330,10 @@ private: return; } - ///> our actual direction + ///< our actual direction Directions m_dir; - ///> Are we routing on 45 or 90 degree increments + ///< Are we routing on 45 or 90 degree increments bool m_90deg; }; diff --git a/libs/kimath/include/geometry/seg.h b/libs/kimath/include/geometry/seg.h index f0028101c8..cf0a291041 100644 --- a/libs/kimath/include/geometry/seg.h +++ b/libs/kimath/include/geometry/seg.h @@ -2,9 +2,10 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN - * @author Tomasz Wlostowski * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * + * @author Tomasz Wlostowski + * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 @@ -48,8 +49,8 @@ public: VECTOR2I A; VECTOR2I B; - /** Default constructor - * Creates an empty (0, 0) segment + /** + * Create an empty (0, 0) segment. */ SEG() { @@ -57,8 +58,7 @@ public: } /** - * Constructor - * Creates a segment between (aX1, aY1) and (aX2, aY2) + * Create a segment between (aX1, aY1) and (aX2, aY2). */ SEG( int aX1, int aY1, int aX2, int aY2 ) : A( VECTOR2I( aX1, aY1 ) ), @@ -68,8 +68,7 @@ public: } /** - * Constructor - * Creates a segment between (aA) and (aB) + * Create a segment between (aA) and (aB). */ SEG( const VECTOR2I& aA, const VECTOR2I& aB ) : A( aA ), @@ -79,8 +78,8 @@ public: } /** - * Constructor - * Creates a segment between (aA) and (aB), referenced to a multi-segment shape + * Create a segment between (aA) and (aB), referenced to a multi-segment shape. + * * @param aA reference to the start point in the parent shape * @param aB reference to the end point in the parent shape * @param aIndex index of the segment within the parent shape @@ -93,7 +92,7 @@ public: } /** - * Copy constructor + * Copy constructor. */ SEG( const SEG& aSeg ) : A( aSeg.A ), @@ -127,19 +126,17 @@ public: } /** - * Function LineProject() - * - * Computes the perpendicular projection point of aP on a line passing through + * Compute the perpendicular projection point of aP on a line passing through * ends of the segment. + * * @param aP point to project * @return projected point */ VECTOR2I LineProject( const VECTOR2I& aP ) const; /** - * Function Side() + * Determine on which side of directed line passing via segment ends point aP lies. * - * Determines on which side of directed line passing via segment ends point aP lies. * @param aP point to determine the orientation wrs to self * @return: < 0: left, 0 : on the line, > 0 : right */ @@ -151,10 +148,9 @@ public: } /** - * Function LineDistance() - * - * Returns the closest Euclidean distance between point aP and the line defined by + * Return the closest Euclidean distance between point aP and the line defined by * the ends of segment (this). + * * @param aP the point to test * @param aDetermineSide: when true, the sign of the returned value indicates * the side of the line at which we are (negative = left) @@ -163,23 +159,22 @@ public: int LineDistance( const VECTOR2I& aP, bool aDetermineSide = false ) const; /** - * Function NearestPoint() + * Compute a point on the segment (this) that is closest to point \a aP. * - * Computes a point on the segment (this) that is closest to point aP. * @return the nearest point */ const VECTOR2I NearestPoint( const VECTOR2I &aP ) const; /** - * Computes a point on the segment (this) that is closest to any point on aSeg. + * Compute a point on the segment (this) that is closest to any point on \a aSeg. + * * @return the nearest point */ const VECTOR2I NearestPoint( const SEG &aSeg ) const; /** - * Function Intersect() + * Compute intersection point of segment (this) with segment \a aSeg. * - * Computes intersection point of segment (this) with segment aSeg. * @param aSeg: segment to intersect with * @param aIgnoreEndpoints: don't treat corner cases (i.e. end of one segment touching the * other) as intersections. @@ -190,9 +185,8 @@ public: bool aLines = false ) const; /** - * Function IntersectLines() + * Compute the intersection point of lines passing through ends of (this) and \a aSeg. * - * Computes the intersection point of lines passing through ends of (this) and aSeg * @param aSeg segment defining the line to intersect with * @return intersection point, if exists */ @@ -202,18 +196,16 @@ public: } /** - * Function PerpendicularSeg() - * - * Computes a segment perpendicular to this one, passing through point aP + * Compute a segment perpendicular to this one, passing through point \a aP. + * * @param aP Point through which the new segment will pass * @return SEG perpendicular to this passing through point aP */ SEG PerpendicularSeg( const VECTOR2I& aP ) const; /** - * Function ParallelSeg() - * - * Computes a segment parallel to this one, passing through point aP + * Compute a segment parallel to this one, passing through point \a aP. + * * @param aP Point through which the new segment will pass * @return SEG parallel to this passing through point aP */ @@ -224,9 +216,8 @@ public: ecoord SquaredDistance( const SEG& aSeg ) const; /** - * Function Distance() + * Compute minimum Euclidean distance to segment \a aSeg. * - * Computes minimum Euclidean distance to segment aSeg. * @param aSeg other segment * @return minimum distance */ @@ -241,9 +232,8 @@ public: } /** - * Function Distance() + * Compute minimum Euclidean distance to point \a aP. * - * Computes minimum Euclidean distance to point aP. * @param aP the point * @return minimum distance */ @@ -260,10 +250,9 @@ public: } /** - * Function Collinear() + * Check if segment aSeg lies on the same line as (this). * - * Checks if segment aSeg lies on the same line as (this). - * @param aSeg the segment to chech colinearity with + * @param aSeg the segment to check colinearity with * @return true, when segments are collinear. */ bool Collinear( const SEG& aSeg ) const @@ -299,7 +288,6 @@ public: return std::abs( dist1 - dist2 ) <= 1; } - bool ApproxPerpendicular( const SEG& aSeg ) const { SEG perp = PerpendicularSeg( A ); @@ -345,9 +333,8 @@ public: } /** - * Function Length() + * Return the length (this). * - * Returns the length (this) * @return length */ int Length() const @@ -363,9 +350,9 @@ public: ecoord TCoef( const VECTOR2I& aP ) const; /** - * Function Index() + * Return the index of this segment in its parent shape (applicable only to non-local + * segments). * - * Return the index of this segment in its parent shape (applicable only to non-local segments) * @return index value */ int Index() const @@ -385,7 +372,7 @@ public: return SEG( B, A ); } - ///> Returns the center point of the line + ///< Returns the center point of the line VECTOR2I Center() const { return A + ( B - A ) / 2; @@ -395,7 +382,7 @@ private: bool ccw( const VECTOR2I& aA, const VECTOR2I& aB, const VECTOR2I &aC ) const; private: - ///> index withing the parent shape (used when m_is_local == false) + ///< index withing the parent shape (used when m_is_local == false) int m_index; }; diff --git a/libs/kimath/include/geometry/shape.h b/libs/kimath/include/geometry/shape.h index 4eddfb98c2..bf30a21ca8 100644 --- a/libs/kimath/include/geometry/shape.h +++ b/libs/kimath/include/geometry/shape.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -34,22 +35,21 @@ class SHAPE_LINE_CHAIN; /** - * Enum SHAPE_TYPE - * Lists all supported shapes + * Lists all supported shapes. */ enum SHAPE_TYPE { - SH_RECT = 0, ///> axis-aligned rectangle - SH_SEGMENT, ///> line segment - SH_LINE_CHAIN, ///> line chain (polyline) - SH_CIRCLE, ///> circle - SH_SIMPLE, ///> simple polygon - SH_POLY_SET, ///> set of polygons (with holes, etc.) - SH_COMPOUND, ///> compound shape, consisting of multiple simple shapes - SH_ARC, ///> circular arc - SH_NULL, ///> empty shape (no shape...), - SH_POLY_SET_TRIANGLE ///> a single triangle belonging to a POLY_SET triangulation + SH_RECT = 0, ///< axis-aligned rectangle + SH_SEGMENT, ///< line segment + SH_LINE_CHAIN, ///< line chain (polyline) + SH_CIRCLE, ///< circle + SH_SIMPLE, ///< simple polygon + SH_POLY_SET, ///< set of polygons (with holes, etc.) + SH_COMPOUND, ///< compound shape, consisting of multiple simple shapes + SH_ARC, ///< circular arc + SH_NULL, ///< empty shape (no shape...), + SH_POLY_SET_TRIANGLE ///< a single triangle belonging to a POLY_SET triangulation }; static inline wxString SHAPE_TYPE_asString( SHAPE_TYPE a ) @@ -77,23 +77,18 @@ class SHAPE_BASE { public: /** - * Constructor - * - * Creates an empty shape of type aType + * Create an empty shape of type aType */ - SHAPE_BASE( SHAPE_TYPE aType ) : m_type( aType ) {} - // Destructor virtual ~SHAPE_BASE() {} /** - * Function Type() + * Return the type of the shape. * - * Returns the type of the shape. * @retval the type */ SHAPE_TYPE Type() const @@ -111,40 +106,34 @@ public: virtual void GetIndexableSubshapes( std::vector& aSubshapes ) { } protected: - ///> type of our shape + ///< type of our shape SHAPE_TYPE m_type; }; /** - * SHAPE - * - * Represents an abstract shape on 2D plane. + * An abstract shape on 2D plane. */ class SHAPE : public SHAPE_BASE { public: /** - * @brief This is the minimum precision for all the points in a shape + * This is the minimum precision for all the points in a shape. */ static const int MIN_PRECISION_IU = 4; /** - * Constructor - * - * Creates an empty shape of type aType + * Create an empty shape of type \a aType. */ SHAPE( SHAPE_TYPE aType ) : SHAPE_BASE( aType ) {} - // Destructor virtual ~SHAPE() {} /** - * Function Clone() + * Return a dynamically allocated copy of the shape. * - * Returns a dynamically allocated copy of the shape * @retval copy of the shape */ virtual SHAPE* Clone() const @@ -154,9 +143,8 @@ public: }; /** - * Function IsNull() + * Return true if the shape is a null shape. * - * Returns true if the shape is a null shape. * @retval true if null :-) */ bool IsNull() const @@ -165,10 +153,9 @@ public: } /** - * Function Collide() - * - * Checks if the boundary of shape (this) lies closer to the point aP than aClearance, + * Check if the boundary of shape (this) lies closer to the point \a aP than \a aClearance, * indicating a collision. + * * @param aActual [out] an optional pointer to an int to store the actual distance in the * event of a collision. * @param aLocation [out] an option pointer to a point to store a nearby location in the @@ -182,10 +169,9 @@ public: } /** - * Function Collide() - * - * Checks if the boundary of shape (this) lies closer to the shape aShape than aClearance, + * Check if the boundary of shape (this) lies closer to the shape \a aShape than \a aClearance, * indicating a collision. + * * @param aShape shape to check collision against * @param aClearance minimum clearance * @param aMTV minimum translation vector @@ -201,10 +187,9 @@ public: VECTOR2I* aLocation = nullptr ) const; /** - * Function Collide() - * - * Checks if the boundary of shape (this) lies closer to the segment aSeg than aClearance, + * Check if the boundary of shape (this) lies closer to the segment \a aSeg than \a aClearance, * indicating a collision. + * * @param aActual [out] an optional pointer to an int to be updated with the actual distance * int the event of a collision. * @param aLocation [out] an option pointer to a point to store a nearby location in the @@ -215,20 +200,17 @@ public: VECTOR2I* aLocation = nullptr ) const = 0; /** - * Function BBox() + * Compute a bounding box of the shape, with a margin of \a aClearance a collision. * - * Computes a bounding box of the shape, with a margin of aClearance - * a collision. - * @param aClearance how much the bounding box is expanded wrs to the minimum enclosing rectangle - * for the shape. + * @param aClearance how much the bounding box is expanded wrs to the minimum enclosing + * rectangle for the shape. * @return the bounding box. */ virtual const BOX2I BBox( int aClearance = 0 ) const = 0; /** - * Function Centre() + * Compute a center-of-mass of the shape. * - * Computes a center-of-mass of the shape * @return the center-of-mass point */ virtual VECTOR2I Centre() const @@ -237,9 +219,8 @@ public: } /** - * Function Rotate - * @param aCenter is the rotation center - * @param aAngle rotation angle in radians + * @param aCenter is the rotation center. + * @param aAngle rotation angle in radians. */ virtual void Rotate( double aAngle, const VECTOR2I& aCenter = { 0, 0 } ) = 0; @@ -264,15 +245,13 @@ public: { } - // Destructor virtual ~SHAPE_LINE_CHAIN_BASE() { } /** - * Function Collide() + * Check if point \a aP lies closer to us than \a aClearance. * - * Checks if point aP lies closer to us than aClearance. * @param aP the point to check for collisions with * @param aClearance minimum distance that does not qualify as a collision. * @param aActual an optional pointer to an int to store the actual distance in the event @@ -283,9 +262,8 @@ public: VECTOR2I* aLocation = nullptr ) const override; /** - * Function Collide() + * Check if segment \a aSeg lies closer to us than \a aClearance. * - * Checks if segment aSeg lies closer to us than aClearance. * @param aSeg the segment to check for collisions with * @param aClearance minimum distance that does not qualify as a collision. * @param aActual an optional pointer to an int to store the actual distance in the event @@ -299,10 +277,9 @@ public: SEG::ecoord SquaredDistance( const VECTOR2I& aP, bool aOutlineOnly = false ) const; /** - * Function PointInside() - * - * Checks if point aP lies inside a polygon (any type) defined by the line chain. + * Check if point \a aP lies inside a polygon (any type) defined by the line chain. * For closed shapes only. + * * @param aPt point to check * @param aUseBBoxCache gives better peformance if the bounding box caches have been * generated. @@ -311,18 +288,16 @@ public: bool PointInside( const VECTOR2I& aPt, int aAccuracy = 0, bool aUseBBoxCache = false ) const; /** - * Function PointOnEdge() + * Check if point \a aP lies on an edge or vertex of the line chain. * - * Checks if point aP lies on an edge or vertex of the line chain. * @param aP point to check * @return true if the point lies on the edge. */ bool PointOnEdge( const VECTOR2I& aP, int aAccuracy = 0 ) const; /** - * Function EdgeContainingPoint() + * Check if point \a aP lies on an edge or vertex of the line chain. * - * Checks if point aP lies on an edge or vertex of the line chain. * @param aP point to check * @return index of the first edge containing the point, otherwise negative */ diff --git a/libs/kimath/include/geometry/shape_poly_set.h b/libs/kimath/include/geometry/shape_poly_set.h index 17766b19e9..00201e0787 100644 --- a/libs/kimath/include/geometry/shape_poly_set.h +++ b/libs/kimath/include/geometry/shape_poly_set.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015-2019 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Alejandro García Montoro * @@ -46,9 +48,7 @@ /** - * SHAPE_POLY_SET - * - * Represents a set of closed polygons. Polygons may be nonconvex, self-intersecting + * Represent a set of closed polygons. Polygons may be nonconvex, self-intersecting * and have holes. Provides boolean operations (using Clipper library as the backend). * * Let us define the terms used on this class to clarify methods names and comments: @@ -64,9 +64,9 @@ class SHAPE_POLY_SET : public SHAPE { public: - ///> represents a single polygon outline with holes. The first entry is the outline, - ///> the remaining (if any), are the holes - ///> N.B. SWIG only supports typedef, so avoid c++ 'using' keyword + ///< represents a single polygon outline with holes. The first entry is the outline, + ///< the remaining (if any), are the holes + ///< N.B. SWIG only supports typedef, so avoid c++ 'using' keyword typedef std::vector POLYGON; class TRIANGULATED_POLYGON @@ -179,8 +179,6 @@ public: }; /** - * Struct VERTEX_INDEX - * * Structure to hold the necessary information in order to index a vertex on a * SHAPE_POLY_SET object: the polygon index, the contour index relative to the polygon and * the vertex index relative the contour. @@ -200,8 +198,6 @@ public: } VERTEX_INDEX; /** - * ITERATOR_TEMPLATE - * * Base class for iterating over all vertices in a given SHAPE_POLY_SET. */ template @@ -210,18 +206,17 @@ public: public: /** - * Function IsEndContour. - * @return bool - true if the current vertex is the last one of the current contour - * (outline or hole); false otherwise. + * @return true if the current vertex is the last one of the current contour + * (outline or hole); false otherwise. */ bool IsEndContour() const { - return m_currentVertex + 1 == m_poly->CPolygon( m_currentPolygon )[m_currentContour].PointCount(); + return m_currentVertex + 1 == + m_poly->CPolygon( m_currentPolygon )[m_currentContour].PointCount(); } /** - * Function IsLastOutline. - * @return bool - true if the current outline is the last one; false otherwise. + * @return true if the current outline is the last one; false otherwise. */ bool IsLastPolygon() const { @@ -243,9 +238,8 @@ public: } /** - * Function Advance - * advances the indices of the current vertex/outline/contour, checking whether the - * vertices in the holes have to be iterated through + * Advance the indices of the current vertex/outline/contour, checking whether the + * vertices in the holes have to be iterated through. */ void Advance() { @@ -257,7 +251,8 @@ public: if( m_iterateHoles ) { // If the last vertex of the contour was reached, advance the contour index - if( m_currentVertex >= m_poly->CPolygon( m_currentPolygon )[m_currentContour].PointCount() ) + if( m_currentVertex >= + m_poly->CPolygon( m_currentPolygon )[m_currentContour].PointCount() ) { m_currentVertex = 0; m_currentContour++; @@ -310,8 +305,7 @@ public: } /** - * Function GetIndex - * @return VERTEX_INDEX - indices of the current polygon, contour and vertex. + * @return the indices of the current polygon, contour and vertex. */ VERTEX_INDEX GetIndex() { @@ -336,8 +330,6 @@ public: }; /** - * SEGMENT_ITERATOR_TEMPLATE - * * Base class for iterating over all segments in a given SHAPE_POLY_SET. */ template @@ -345,8 +337,7 @@ public: { public: /** - * Function IsLastOutline. - * @return bool - true if the current outline is the last one. + * @return true if the current outline is the last one. */ bool IsLastPolygon() const { @@ -359,9 +350,8 @@ public: } /** - * Function Advance - * advances the indices of the current vertex/outline/contour, checking whether the - * vertices in the holes have to be iterated through + * Advance the indices of the current vertex/outline/contour, checking whether the + * vertices in the holes have to be iterated through. */ void Advance() { @@ -370,19 +360,19 @@ public: int last; // Check whether the user wants to iterate through the vertices of the holes - // and behave accordingly + // and behave accordingly. if( m_iterateHoles ) { last = m_poly->CPolygon( m_currentPolygon )[m_currentContour].SegmentCount(); - // If the last vertex of the contour was reached, advance the contour index + // If the last vertex of the contour was reached, advance the contour index. if( m_currentSegment >= last ) { m_currentSegment = 0; m_currentContour++; // If the last contour of the current polygon was reached, advance the - // outline index + // outline index. int totalContours = m_poly->CPolygon( m_currentPolygon ).size(); if( m_currentContour >= totalContours ) @@ -426,8 +416,7 @@ public: } /** - * Function GetIndex - * @return VERTEX_INDEX - indices of the current polygon, contour and vertex. + * @return the indices of the current polygon, contour and vertex. */ VERTEX_INDEX GetIndex() { @@ -441,20 +430,18 @@ public: } /** - * Function IsAdjacent - * @param aOther is an iterator pointing to another segment. - * @return bool - true if both iterators point to the same segment of the same - * contour of the same polygon of the same polygon set; false - * otherwise. + * @param aOther is an iterator pointing to another segment. + * @return true if both iterators point to the same segment of the same contour of + * the same polygon of the same polygon set; false otherwise. */ bool IsAdjacent( SEGMENT_ITERATOR_TEMPLATE aOther ) { // Check that both iterators point to the same contour of the same polygon of the - // same polygon set + // same polygon set. if( m_poly == aOther.m_poly && m_currentPolygon == aOther.m_currentPolygon && m_currentContour == aOther.m_currentContour ) { - // Compute the total number of segments + // Compute the total number of segments. int numSeg; numSeg = m_poly->CPolygon( m_currentPolygon )[m_currentContour].SegmentCount(); @@ -501,6 +488,7 @@ public: /** * Copy constructor SHAPE_POLY_SET * Performs a deep copy of \p aOther into \p this. + * * @param aOther is the SHAPE_POLY_SET object that will be copied. */ SHAPE_POLY_SET( const SHAPE_POLY_SET& aOther ); @@ -521,128 +509,127 @@ public: virtual void GetIndexableSubshapes( std::vector& aSubshapes ) override; /** - * Function GetRelativeIndices - * - * Converts a global vertex index ---i.e., a number that globally identifies a vertex in a + * Convert a global vertex index ---i.e., a number that globally identifies a vertex in a * concatenated list of all vertices in all contours--- and get the index of the vertex * relative to the contour relative to the polygon in which it is. - * @param aGlobalIdx is the global index of the corner whose structured index wants to - * be found + * + * @param aGlobalIdx is the global index of the corner whose structured index wants to + * be found * @param aRelativeIndices is a pointer to the set of relative indices to store. - * @return bool - true if the global index is correct and the information in - * aRelativeIndices is valid; false otherwise. + * @return true if the global index is correct and the information in \a aRelativeIndices + * is valid; false otherwise. */ - bool GetRelativeIndices( int aGlobalIdx, VERTEX_INDEX* aRelativeIndices) const; + bool GetRelativeIndices( int aGlobalIdx, VERTEX_INDEX* aRelativeIndices ) const; /** - * Function GetGlobalIndex - * computes the global index of a vertex from the relative indices of polygon, contour and + * Compute the global index of a vertex from the relative indices of polygon, contour and * vertex. + * * @param aRelativeIndices is the set of relative indices. - * @param aGlobalIdx [out] is the computed global index. - * @return bool - true if the relative indices are correct; false otherwise. The computed - * global index is returned in the \p aGlobalIdx reference. + * @param aGlobalIdx [out] is the computed global index. + * @return true if the relative indices are correct; false otherwise. The computed + * global index is returned in the \p aGlobalIdx reference. */ bool GetGlobalIndex( VERTEX_INDEX aRelativeIndices, int& aGlobalIdx ); /// @copydoc SHAPE::Clone() SHAPE* Clone() const override; - ///> Creates a new empty polygon in the set and returns its index + ///< Creates a new empty polygon in the set and returns its index int NewOutline(); - ///> Creates a new hole in a given outline + ///< Creates a new hole in a given outline int NewHole( int aOutline = -1 ); - ///> Adds a new outline to the set and returns its index + ///< Adds a new outline to the set and returns its index int AddOutline( const SHAPE_LINE_CHAIN& aOutline ); - ///> Adds a new hole to the given outline (default: last) and returns its index + ///< Adds a new hole to the given outline (default: last) and returns its index int AddHole( const SHAPE_LINE_CHAIN& aHole, int aOutline = -1 ); - ///> Appends a vertex at the end of the given outline/hole (default: the last outline) + ///< Appends a vertex at the end of the given outline/hole (default: the last outline) /** - * Function Append - * adds a new vertex to the contour indexed by \p aOutline and \p aHole (defaults to the + * Add a new vertex to the contour indexed by \p aOutline and \p aHole (defaults to the * outline of the last polygon). + * * @param x is the x coordinate of the new vertex. * @param y is the y coordinate of the new vertex. * @param aOutline is the index of the polygon. * @param aHole is the index of the hole (-1 for the main outline), * @param aAllowDuplication is a flag to indicate whether it is allowed to add this * corner even if it is duplicated. - * @return int - the number of corners of the selected contour after the addition. + * @return the number of corners of the selected contour after the addition. */ - int Append( int x, int y, int aOutline = -1, int aHole = -1, - bool aAllowDuplication = false ); + int Append( int x, int y, int aOutline = -1, int aHole = -1, bool aAllowDuplication = false ); - ///> Merges polygons from two sets. + ///< Merge polygons from two sets. void Append( const SHAPE_POLY_SET& aSet ); - ///> Appends a vertex at the end of the given outline/hole (default: the last outline) + ///< Append a vertex at the end of the given outline/hole (default: the last outline) void Append( const VECTOR2I& aP, int aOutline = -1, int aHole = -1 ); /** - * Function InsertVertex - * Adds a vertex in the globally indexed position aGlobalIndex. - * @param aGlobalIndex is the global index of the position in which teh new vertex will be + * Adds a vertex in the globally indexed position \a aGlobalIndex. + * + * @param aGlobalIndex is the global index of the position in which the new vertex will be * inserted. * @param aNewVertex is the new inserted vertex. */ void InsertVertex( int aGlobalIndex, VECTOR2I aNewVertex ); - ///> Returns the index-th vertex in a given hole outline within a given outline + ///< Return the index-th vertex in a given hole outline within a given outline const VECTOR2I& CVertex( int aIndex, int aOutline, int aHole ) const; - ///> Returns the aGlobalIndex-th vertex in the poly set + ///< Return the aGlobalIndex-th vertex in the poly set const VECTOR2I& CVertex( int aGlobalIndex ) const; - ///> Returns the index-th vertex in a given hole outline within a given outline + ///< Return the index-th vertex in a given hole outline within a given outline const VECTOR2I& CVertex( VERTEX_INDEX aIndex ) const; /** - * Returns the global indexes of the previous and the next corner - * of the aGlobalIndex-th corner of a contour in the polygon set. - * they are often aGlobalIndex-1 and aGlobalIndex+1, but not for the first and last + * Return the global indexes of the previous and the next corner of the \a aGlobalIndex-th + * corner of a contour in the polygon set. + * + * They are often aGlobalIndex-1 and aGlobalIndex+1, but not for the first and last * corner of the contour. + * * @param aGlobalIndex is index of the corner, globally indexed between all edges in all * contours - * @param aPrevious - the globalIndex of the previous corner of the same contour. - * @param aNext - the globalIndex of the next corner of the same contour. + * @param aPrevious is the globalIndex of the previous corner of the same contour. + * @param aNext is the globalIndex of the next corner of the same contour. * @return true if OK, false if aGlobalIndex is out of range */ bool GetNeighbourIndexes( int aGlobalIndex, int* aPrevious, int* aNext ); - /** - * Function IsPolygonSelfIntersecting. - * Checks whether the aPolygonIndex-th polygon in the set is self intersecting. - * @param aPolygonIndex index of the polygon that wants to be checked. - * @return bool - true if the aPolygonIndex-th polygon is self intersecting, false - * otherwise. + * Check whether the aPolygonIndex-th polygon in the set is self intersecting. + * + * @param aPolygonIndex is the index of the polygon that wants to be checked. + * @return true if the \a aPolygonIndex-th polygon is self intersecting, false otherwise. */ bool IsPolygonSelfIntersecting( int aPolygonIndex ) const; /** - * Function IsSelfIntersecting - * Checks whether any of the polygons in the set is self intersecting. - * @return bool - true if any of the polygons is self intersecting, false otherwise. + * Check whether any of the polygons in the set is self intersecting. + * + * @return true if any of the polygons is self intersecting, false otherwise. */ bool IsSelfIntersecting() const; - ///> Returns the number of triangulated polygons + ///< Return the number of triangulated polygons unsigned int TriangulatedPolyCount() const { return m_triangulatedPolys.size(); } - ///> Returns the number of outlines in the set + ///< Return the number of outlines in the set int OutlineCount() const { return m_polys.size(); } - ///> Returns the number of vertices in a given outline/hole + ///< Return the number of vertices in a given outline/hole int VertexCount( int aOutline = -1, int aHole = -1 ) const; - ///> Returns the number of holes in a given outline + ///< Returns the number of holes in a given outline int HoleCount( int aOutline ) const { - if( ( aOutline < 0 ) || (aOutline >= (int)m_polys.size()) || (m_polys[aOutline].size() < 2) ) + if( ( aOutline < 0 ) || ( aOutline >= (int) m_polys.size() ) + || ( m_polys[aOutline].size() < 2 ) ) return 0; // the first polygon in m_polys[aOutline] is the main contour, @@ -650,7 +637,7 @@ public: return m_polys[aOutline].size() - 1; } - ///> Returns the reference to aIndex-th outline in the set + ///< Return the reference to aIndex-th outline in the set SHAPE_LINE_CHAIN& Outline( int aIndex ) { return m_polys[aIndex][0]; @@ -662,13 +649,13 @@ public: } /** - * Function Subset - * returns a subset of the polygons in this set, the ones between aFirstPolygon and - * aLastPolygon. + * Return a subset of the polygons in this set, the ones between \a aFirstPolygon and + * \a aLastPolygon. + * * @param aFirstPolygon is the first polygon to be included in the returned set. - * @param aLastPolygon is the first polygon to be excluded of the returned set. - * @return SHAPE_POLY_SET - a set containing the polygons between aFirstPolygon (included) - * and aLastPolygon (excluded). + * @param aLastPolygon is the last polygon to be excluded of the returned set. + * @return a set containing the polygons between \a aFirstPolygon (included) + * and \a aLastPolygon (excluded). */ SHAPE_POLY_SET Subset( int aFirstPolygon, int aLastPolygon ); @@ -677,13 +664,13 @@ public: return Subset( aPolygonIndex, aPolygonIndex + 1 ); } - ///> Returns the reference to aHole-th hole in the aIndex-th outline + ///< Return the reference to aHole-th hole in the aIndex-th outline SHAPE_LINE_CHAIN& Hole( int aOutline, int aHole ) { return m_polys[aOutline][aHole + 1]; } - ///> Returns the aIndex-th subpolygon in the set + ///< Return the aIndex-th subpolygon in the set POLYGON& Polygon( int aIndex ) { return m_polys[aIndex]; @@ -715,9 +702,9 @@ public: } /** - * Function Iterate - * returns an object to iterate through the points of the polygons between \p aFirst and + * Return an object to iterate through the points of the polygons between \p aFirst and * \p aLast. + * * @param aFirst is the first polygon whose points will be iterated. * @param aLast is the last polygon whose points will be iterated. * @param aIterateHoles is a flag to indicate whether the points of the holes should be @@ -739,10 +726,9 @@ public: } /** - * Function Iterate - * @param aOutline the index of the polygon to be iterated. - * @return ITERATOR - an iterator object to visit all points in the main outline of the - * aOutline-th polygon, without visiting the points in the holes. + * @param aOutline is the index of the polygon to be iterated. + * @return an iterator object to visit all points in the main outline of the + * \a aOutline-th polygon, without visiting the points in the holes. */ ITERATOR Iterate( int aOutline ) { @@ -750,10 +736,9 @@ public: } /** - * Function IterateWithHoles - * @param aOutline the index of the polygon to be iterated. - * @return ITERATOR - an iterator object to visit all points in the main outline of the - * aOutline-th polygon, visiting also the points in the holes. + * @param aOutline the index of the polygon to be iterated. + * @return an iterator object to visit all points in the main outline of the + * \a aOutline-th polygon, visiting also the points in the holes. */ ITERATOR IterateWithHoles( int aOutline ) { @@ -761,9 +746,8 @@ public: } /** - * Function Iterate - * @return ITERATOR - an iterator object to visit all points in all outlines of the set, - * without visiting the points in the holes. + * @return an iterator object to visit all points in all outlines of the set, + * without visiting the points in the holes. */ ITERATOR Iterate() { @@ -771,9 +755,8 @@ public: } /** - * Function IterateWithHoles - * @return ITERATOR - an iterator object to visit all points in all outlines of the set, - * visiting also the points in the holes. + * @return an iterator object to visit all points in all outlines of the set, + * visiting also the points in the holes. */ ITERATOR IterateWithHoles() { @@ -834,8 +817,8 @@ public: return iter; } - ///> Returns an iterator object, for iterating between aFirst and aLast outline, with or - /// without holes (default: without) + ///< Return an iterator object, for iterating between aFirst and aLast outline, with or + ///< without holes (default: without) SEGMENT_ITERATOR IterateSegments( int aFirst, int aLast, bool aIterateHoles = false ) { SEGMENT_ITERATOR iter; @@ -850,8 +833,8 @@ public: return iter; } - ///> Returns an iterator object, for iterating between aFirst and aLast outline, with or - /// without holes (default: without) + ///< Return an iterator object, for iterating between aFirst and aLast outline, with or + ///< without holes (default: without) CONST_SEGMENT_ITERATOR CIterateSegments( int aFirst, int aLast, bool aIterateHoles = false ) const { @@ -867,54 +850,55 @@ public: return iter; } - ///> Returns an iterator object, for iterating aPolygonIdx-th polygon edges + ///< Return an iterator object, for iterating aPolygonIdx-th polygon edges. SEGMENT_ITERATOR IterateSegments( int aPolygonIdx ) { return IterateSegments( aPolygonIdx, aPolygonIdx ); } - ///> Returns an iterator object, for iterating aPolygonIdx-th polygon edges + ///< Return an iterator object, for iterating aPolygonIdx-th polygon edges. CONST_SEGMENT_ITERATOR CIterateSegments( int aPolygonIdx ) const { return CIterateSegments( aPolygonIdx, aPolygonIdx ); } - ///> Returns an iterator object, for all outlines in the set (no holes) + ///< Return an iterator object, for all outlines in the set (no holes). SEGMENT_ITERATOR IterateSegments() { return IterateSegments( 0, OutlineCount() - 1 ); } - ///> Returns an iterator object, for all outlines in the set (with holes) + ///< Return an iterator object, for all outlines in the set (with holes). SEGMENT_ITERATOR IterateSegmentsWithHoles() { return IterateSegments( 0, OutlineCount() - 1, true ); } - ///> Returns an iterator object, for the aOutline-th outline in the set (with holes) + ///< Return an iterator object, for the \a aOutline-th outline in the set (with holes). SEGMENT_ITERATOR IterateSegmentsWithHoles( int aOutline ) { return IterateSegments( aOutline, aOutline, true ); } - ///> Returns an iterator object, for the aOutline-th outline in the set (with holes) + ///< Return an iterator object, for the \a aOutline-th outline in the set (with holes). CONST_SEGMENT_ITERATOR CIterateSegmentsWithHoles() const { return CIterateSegments( 0, OutlineCount() - 1, true ); } - ///> Returns an iterator object, for the aOutline-th outline in the set (with holes) + ///< Return an iterator object, for the \a aOutline-th outline in the set (with holes). CONST_SEGMENT_ITERATOR CIterateSegmentsWithHoles( int aOutline ) const { return CIterateSegments( aOutline, aOutline, true ); } - /** operations on polygons use a aFastMode param - * if aFastMode is PM_FAST (true) the result can be a weak polygon - * if aFastMode is PM_STRICTLY_SIMPLE (false) (default) the result is (theorically) a strictly - * simple polygon, but calculations can be really significantly time consuming - * Most of time PM_FAST is preferable. - * PM_STRICTLY_SIMPLE can be used in critical cases (Gerber output for instance) + /** + * Operations on polygons use a \a aFastMode param + * if aFastMode is #PM_FAST (true) the result can be a weak polygon + * if aFastMode is #PM_STRICTLY_SIMPLE (false) (default) the result is (theoretically) a + * strictly simple polygon, but calculations can be really significantly time consuming + * Most of time #PM_FAST is preferable. + * #PM_STRICTLY_SIMPLE can be used in critical cases (Gerber output for instance) */ enum POLYGON_MODE { @@ -922,34 +906,34 @@ public: PM_STRICTLY_SIMPLE = false }; - ///> Performs boolean polyset union - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset union + ///< For \a aFastMode meaning, see function booleanOp void BooleanAdd( const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - ///> Performs boolean polyset difference - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset difference + ///< For \a aFastMode meaning, see function booleanOp void BooleanSubtract( const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - ///> Performs boolean polyset intersection - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset intersection + ///< For \a aFastMode meaning, see function booleanOp void BooleanIntersection( const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - ///> Performs boolean polyset union between a and b, store the result in it self - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset union between a and b, store the result in it self + ///< For \a aFastMode meaning, see function booleanOp void BooleanAdd( const SHAPE_POLY_SET& a, const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - ///> Performs boolean polyset difference between a and b, store the result in it self - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset difference between a and b, store the result in it self + ///< For \a aFastMode meaning, see function booleanOp void BooleanSubtract( const SHAPE_POLY_SET& a, const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - ///> Performs boolean polyset intersection between a and b, store the result in it self - ///> For aFastMode meaning, see function booleanOp + ///< Perform boolean polyset intersection between a and b, store the result in it self + ///< For \a aFastMode meaning, see function booleanOp void BooleanIntersection( const SHAPE_POLY_SET& a, const SHAPE_POLY_SET& b, POLYGON_MODE aFastMode ); - enum CORNER_STRATEGY ///< define how inflate transform build inflated polygon + enum CORNER_STRATEGY ///< define how inflate transform build inflated polygon { ALLOW_ACUTE_CORNERS, ///< just inflate the polygon. Acute angles create spikes CHAMFER_ACUTE_CORNERS, ///< Acute angles are chamfered @@ -962,16 +946,18 @@ public: }; /** - * Performs outline inflation/deflation. Polygons can have holes, but not linked holes - * with main outlines, if aFactor < 0. For those use InflateWithLinkedHoles() to avoid - * odd corners where the link segments meet the outline. + * Perform outline inflation/deflation. * - * @param aAmount - number of units to offset edges - * @param aCircleSegmentsCount - number of segments per 360 degrees to use in curve approx - * @param aCornerStrategy - ALLOW_ACUTE_CORNERS to preserve all angles, - * CHOP_ACUTE_CORNERS to chop angles less than 90°, - * ROUND_ACUTE_CORNERS to round off angles less than 90°, - * ROUND_ALL_CORNERS to round regardless of angles + * Polygons can have holes, but not linked holes with main outlines, if aFactor < 0. For + * those use InflateWithLinkedHoles() to avoid odd corners where the link segments meet + * the outline. + * + * @param aAmount is the number of units to offset edges. + * @param aCircleSegmentsCount is the number of segments per 360 degrees to use in curve approx + * @param aCornerStrategy #ALLOW_ACUTE_CORNERS to preserve all angles, + * #CHOP_ACUTE_CORNERS to chop angles less than 90°, + * #ROUND_ACUTE_CORNERS to round off angles less than 90°, + * #ROUND_ALL_CORNERS to round regardless of angles */ void Inflate( int aAmount, int aCircleSegmentsCount, CORNER_STRATEGY aCornerStrategy = ROUND_ALL_CORNERS ); @@ -983,38 +969,41 @@ public: } /** - * Performs outline inflation/deflation, using round corners. Polygons can have holes, - * and/or linked holes with main outlines. The resulting polygons are laso polygons with - * linked holes to main outlines. For aFastMode meaning, see function booleanOp . + * Perform outline inflation/deflation, using round corners. + * + * Polygons can have holes and/or linked holes with main outlines. The resulting + * polygons are also polygons with linked holes to main outlines. For \a aFastMode + * meaning, see function booleanOp . */ void InflateWithLinkedHoles( int aFactor, int aCircleSegmentsCount, POLYGON_MODE aFastMode ); - ///> Converts a set of polygons with holes to a singe outline with "slits"/"fractures" - ///> connecting the outer ring to the inner holes - ///> For aFastMode meaning, see function booleanOp + ///< Convert a set of polygons with holes to a singe outline with "slits"/"fractures" + ///< connecting the outer ring to the inner holes + ///< For \a aFastMode meaning, see function booleanOp void Fracture( POLYGON_MODE aFastMode ); - ///> Converts a single outline slitted ("fractured") polygon into a set ouf outlines - ///> with holes. + ///< Convert a single outline slitted ("fractured") polygon into a set ouf outlines + ///< with holes. void Unfracture( POLYGON_MODE aFastMode ); - ///> Returns true if the polygon set has any holes. + ///< Return true if the polygon set has any holes. bool HasHoles() const; - ///> Returns true if the polygon set has any holes tha share a vertex. + ///< Return true if the polygon set has any holes that share a vertex. bool HasTouchingHoles() const; - ///> Simplifies the polyset (merges overlapping polys, eliminates degeneracy/self-intersections) - ///> For aFastMode meaning, see function booleanOp + ///< Simplify the polyset (merges overlapping polys, eliminates degeneracy/self-intersections) + ///< For \a aFastMode meaning, see function booleanOp void Simplify( POLYGON_MODE aFastMode ); /** - * Function NormalizeAreaOutlines - * Convert a self-intersecting polygon to one (or more) non self-intersecting polygon(s) + * Convert a self-intersecting polygon to one (or more) non self-intersecting polygon(s). + * * Removes null segments. - * @return int - the polygon count (always >= 1, because there is at least one polygon) - * There are new polygons only if the polygon count is > 1. + * + * @return the polygon count (always >= 1, because there is at least one polygon) + * There are new polygons only if the polygon count is > 1. */ int NormalizeAreaOutlines(); @@ -1028,7 +1017,8 @@ public: void Move( const VECTOR2I& aVector ) override; /** - * Mirrors the line points about y or x (or both) + * Mirror the line points about y or x (or both) + * * @param aX If true, mirror about the y axis (flip x coordinate) * @param aY If true, mirror about the x axis * @param aRef sets the reference point about which to mirror @@ -1036,10 +1026,10 @@ public: void Mirror( bool aX = true, bool aY = false, const VECTOR2I& aRef = { 0, 0 } ); /** - * Function Rotate - * rotates all vertices by a given angle - * @param aCenter is the rotation center - * @param aAngle rotation angle in radians + * Rotate all vertices by a given angle. + * + * @param aCenter is the rotation center. + * @param aAngle is the rotation angle in radians. */ void Rotate( double aAngle, const VECTOR2I& aCenter = { 0, 0 } ) override; @@ -1052,33 +1042,30 @@ public: const BOX2I BBox( int aClearance = 0 ) const override; /** - * Function PointOnEdge() + * Check if point \a aP lies on an edge or vertex of some of the outlines or holes. * - * Checks if point aP lies on an edge or vertex of some of the outlines or holes. * @param aP is the point to check. - * @return bool - true if the point lies on the edge of any polygon. + * @return true if the point lies on the edge of any polygon. */ bool PointOnEdge( const VECTOR2I& aP ) const; /** - * Function Collide() - * - * Checks if the boundary of shape (this) lies closer to the shape aShape than aClearance, + * Check if the boundary of shape (this) lies closer to the shape \a aShape than \a aClearance, * indicating a collision. + * * @param aShape shape to check collision against * @param aClearance minimum clearance * @param aActual [out] an optional pointer to an int to store the actual distance in the * event of a collision. * @param aLocation [out] an option pointer to a point to store a nearby location in the * event of a collision. - * @return true, if there is a collision. + * @return true if there is a collision. */ bool Collide( const SHAPE* aShape, int aClearance = 0, int* aActual = nullptr, VECTOR2I* aLocation = nullptr ) const override; /** - * Function Collide - * Checks whether the point aP is either inside or on the edge of the polygon set. + * Check whether the point \a aP is either inside or on the edge of the polygon set. * * Note that prior to Jul 2020 we considered the edge to *not* be part of the polygon. * However, most other shapes (rects, circles, segments, etc.) include their edges and @@ -1093,14 +1080,13 @@ public: * than aClearance distance, then there is a collision. * @param aActual an optional pointer to an int to store the actual distance in the event * of a collision. - * @return bool - true if the point aP collides with the polygon; false in any other case. + * @return true if the point aP collides with the polygon; false in any other case. */ bool Collide( const VECTOR2I& aP, int aClearance = 0, int* aActual = nullptr, VECTOR2I* aLocation = nullptr ) const override; /** - * Function Collide - * Checks whether the segment aSeg collides with the polygon set (or its edge). + * Check whether the segment \a aSeg collides with the polygon set (or its edge). * * Note that prior to Jul 2020 we considered the edge to *not* be part of the polygon. * However, most other shapes (rects, circles, segments, etc.) include their edges and @@ -1115,16 +1101,15 @@ public: * than aClearance distance, then there is a collision. * @param aActual an optional pointer to an int to store the actual distance in the event * of a collision. - * @return bool - true if the segment aSeg collides with the polygon; - * false in any other case. + * @return true if the segment aSeg collides with the polygon, false in any other case. */ bool Collide( const SEG& aSeg, int aClearance = 0, int* aActual = nullptr, VECTOR2I* aLocation = nullptr ) const override; /** - * Function CollideVertex - * Checks whether aPoint collides with any vertex of any of the contours of the polygon. - * @param aPoint is the VECTOR2I point whose collision with respect to the polygon + * Check whether \a aPoint collides with any vertex of any of the contours of the polygon. + * + * @param aPoint is the #VECTOR2I point whose collision with respect to the polygon * will be tested. * @param aClearance is the security distance; if \p aPoint lies closer to a vertex than * aClearance distance, then there is a collision. @@ -1135,8 +1120,8 @@ public: int aClearance = 0 ) const; /** - * Function CollideEdge - * Checks whether aPoint collides with any edge of any of the contours of the polygon. + * Check whether aPoint collides with any edge of any of the contours of the polygon. + * * @param aPoint is the VECTOR2I point whose collision with respect to the polygon * will be tested. * @param aClearance is the security distance; if \p aPoint lies closer to a vertex than @@ -1148,15 +1133,17 @@ public: int aClearance = 0 ) const; /** - * Constructs BBoxCaches for Contains(), below. These caches MUST be built before a - * group of calls to Contains(). They are NOT kept up-to-date by editing actions. + * Construct BBoxCaches for Contains(), below. + * + * @note These caches **must** be built before a group of calls to Contains(). They are + * **not** kept up-to-date by editing actions. */ void BuildBBoxCaches(); const BOX2I BBoxFromCaches() const; /** - * Returns true if a given subpolygon contains the point aP + * Return true if a given subpolygon contains the point \a aP. * * @param aP is the point to check * @param aSubpolyIndex is the subpolygon to check, or -1 to check all @@ -1168,32 +1155,32 @@ public: bool Contains( const VECTOR2I& aP, int aSubpolyIndex = -1, int aAccuracy = 0, bool aUseBBoxCaches = false ) const; - ///> Returns true if the set is empty (no polygons at all) + ///< Return true if the set is empty (no polygons at all) bool IsEmpty() const { return m_polys.size() == 0; } /** - * Function RemoveVertex - * deletes the aGlobalIndex-th vertex. + * Delete the \a aGlobalIndex-th vertex. + * * @param aGlobalIndex is the global index of the to-be-removed vertex. */ void RemoveVertex( int aGlobalIndex ); /** - * Function RemoveVertex - * deletes the vertex indexed by aIndex (index of polygon, contour and vertex). + * Delete the vertex indexed by \a aRelativeIndex (index of polygon, contour and vertex). + * * @param aRelativeIndices is the set of relative indices of the to-be-removed vertex. */ void RemoveVertex( VERTEX_INDEX aRelativeIndices ); - ///> Removes all outlines & holes (clears) the polygon set. + ///< Remove all outlines & holes (clears) the polygon set. void RemoveAllContours(); /** - * Function RemoveContour - * deletes the aContourIdx-th contour of the aPolygonIdx-th polygon in the set. + * Delete the \a aContourIdx-th contour of the \a aPolygonIdx-th polygon in the set. + * * @param aContourIdx is the index of the contour in the aPolygonIdx-th polygon to be * removed. * @param aPolygonIdx is the index of the polygon in which the to-be-removed contour is. @@ -1202,103 +1189,104 @@ public: void RemoveContour( int aContourIdx, int aPolygonIdx = -1 ); /** - * Function RemoveNullSegments - * looks for null segments; ie, segments whose ends are exactly the same and deletes them. - * @return int - the number of deleted segments. + * Look for null segments; ie, segments whose ends are exactly the same and deletes them. + * + * @return the number of deleted segments. */ int RemoveNullSegments(); /** - * Function SetVertex - * Accessor function to set the position of a specific point - * @param aIndex VERTEX_INDEX of the point to move - * @param aPos destination position of the specified point + * Accessor function to set the position of a specific point. + * + * @param aIndex #VERTEX_INDEX of the point to move. + * @param aPos destination position of the specified point. */ void SetVertex( const VERTEX_INDEX& aIndex, const VECTOR2I& aPos ); /** - * Sets the vertex based on the global index. Throws if the index - * doesn't exist + * Set the vertex based on the global index. + * + * Throws if the index doesn't exist. + * * @param aGlobalIndex global index of the to-be-moved vertex * @param aPos New position on the vertex */ void SetVertex( int aGlobalIndex, const VECTOR2I& aPos ); - ///> Returns total number of vertices stored in the set. + ///< Return total number of vertices stored in the set. int TotalVertices() const; - ///> Deletes aIdx-th polygon from the set + ///< Delete \a aIdx-th polygon from the set. void DeletePolygon( int aIdx ); /** - * Function Chamfer - * returns a chamfered version of the aIndex-th polygon. + * Return a chamfered version of the \a aIndex-th polygon. + * * @param aDistance is the chamfering distance. * @param aIndex is the index of the polygon to be chamfered. - * @return POLYGON - A polygon containing the chamfered version of the aIndex-th polygon. + * @return A polygon containing the chamfered version of the \a aIndex-th polygon. */ POLYGON ChamferPolygon( unsigned int aDistance, int aIndex ); /** - * Function Fillet - * returns a filleted version of the aIndex-th polygon. + * Return a filleted version of the \a aIndex-th polygon. + * * @param aRadius is the fillet radius. * @param aErrorMax is the maximum allowable deviation of the polygon from the circle * @param aIndex is the index of the polygon to be filleted - * @return POLYGON - A polygon containing the filleted version of the aIndex-th polygon. + * @return A polygon containing the filleted version of the \a aIndex-th polygon. */ POLYGON FilletPolygon( unsigned int aRadius, int aErrorMax, int aIndex ); /** - * Function Chamfer - * returns a chamfered version of the polygon set. + * Return a chamfered version of the polygon set. + * * @param aDistance is the chamfering distance. - * @return SHAPE_POLY_SET - A set containing the chamfered version of this set. + * @return A set containing the chamfered version of this set. */ SHAPE_POLY_SET Chamfer( int aDistance ); /** - * Function Fillet - * returns a filleted version of the polygon set. + * Return a filleted version of the polygon set. + * * @param aRadius is the fillet radius. * @param aErrorMax is the maximum allowable deviation of the polygon from the circle - * @return SHAPE_POLY_SET - A set containing the filleted version of this set. + * @return A set containing the filleted version of this set. */ SHAPE_POLY_SET Fillet( int aRadius, int aErrorMax ); /** - * Function DistanceToPolygon - * computes the minimum distance between the aIndex-th polygon and aPoint. + * Compute the minimum distance between the \a aIndex-th polygon and \a aPoint. + * * @param aPoint is the point whose distance to the aIndex-th polygon has to be measured. - * @param aIndex is the index of the polygon whose distace to aPoint has to be measured. + * @param aIndex is the index of the polygon whose distance to aPoint has to be measured. * @param aNearest [out] an optional pointer to be filled in with the point on the * polyset which is closest to aPoint. - * @return int - The minimum distance between aPoint and all the segments of the aIndex-th - * polygon. If the point is contained in the polygon, the distance is zero. + * @return The minimum distance between \a aPoint and all the segments of the \a aIndex-th + * polygon. If the point is contained in the polygon, the distance is zero. */ SEG::ecoord SquaredDistanceToPolygon( VECTOR2I aPoint, int aIndex, VECTOR2I* aNearest ) const; /** - * Function DistanceToPolygon - * computes the minimum distance between the aIndex-th polygon and aSegment with a + * Compute the minimum distance between the aIndex-th polygon and aSegment with a * possible width. + * * @param aSegment is the segment whose distance to the aIndex-th polygon has to be * measured. - * @param aIndex is the index of the polygon whose distace to aPoint has to be measured. + * @param aIndex is the index of the polygon whose distance to aPoint has to be measured. * @param aNearest [out] an optional pointer to be filled in with the point on the * polyset which is closest to aSegment. - * @return int - The minimum distance between aSegment and all the segments of the - * aIndex-th polygon. If the point is contained in the polygon, the - * distance is zero. + * @return The minimum distance between \a aSegment and all the segments of the \a aIndex-th + * polygon. If the point is contained in the polygon, the distance is zero. */ SEG::ecoord SquaredDistanceToPolygon( const SEG& aSegment, int aIndex, VECTOR2I* aNearest) const; /** - * Function SquaredDistance - * computes the minimum distance squared between aPoint and all the polygons in the set. + * Compute the minimum distance squared between aPoint and all the polygons in the set. * Squared distances are used because they avoid the cost of doing square-roots. + * * @param aPoint is the point whose distance to the set has to be measured. * @param aNearest [out] an optional pointer to be filled in with the point on the * polyset which is closest to aPoint. @@ -1308,9 +1296,9 @@ public: SEG::ecoord SquaredDistance( VECTOR2I aPoint, VECTOR2I* aNearest = nullptr ) const; /** - * Function SquaredDistance - * computes the minimum distance squared between aSegment and all the polygons in the set. + * Compute the minimum distance squared between aSegment and all the polygons in the set. * Squared distances are used because they avoid the cost of doing square-roots. + * * @param aSegment is the segment whose distance to the polygon set has to be measured. * @param aSegmentWidth is the width of the segment; defaults to zero. * @param aNearest [out] an optional pointer to be filled in with the point on the @@ -1321,10 +1309,10 @@ public: SEG::ecoord SquaredDistance( const SEG& aSegment, VECTOR2I* aNearest = nullptr ) const; /** - * Function IsVertexInHole. - * checks whether the aGlobalIndex-th vertex belongs to a hole. + * Check whether the \a aGlobalIndex-th vertex belongs to a hole. + * * @param aGlobalIdx is the index of the vertex. - * @return bool - true if the globally indexed aGlobalIdx-th vertex belongs to a hole. + * @return true if the globally indexed \a aGlobalIdx-th vertex belongs to a hole. */ bool IsVertexInHole( int aGlobalIdx ); @@ -1333,15 +1321,16 @@ private: void unfractureSingle ( POLYGON& path ); void importTree( ClipperLib::PolyTree* tree ); - /** Function booleanOp - * this is the engine to execute all polygon boolean transforms - * (AND, OR, ... and polygon simplification (merging overlaping polygons) + /** + * This is the engine to execute all polygon boolean transforms (AND, OR, ... and polygon + * simplification (merging overlapping polygons). + * * @param aType is the transform type ( see ClipperLib::ClipType ) * @param aOtherShape is the SHAPE_LINE_CHAIN to combine with me. * @param aFastMode is an option to choose if the result can be a weak polygon - * or a stricty simple polygon. + * or a strictly simple polygon. * if aFastMode is PM_FAST the result can be a weak polygon - * if aFastMode is PM_STRICTLY_SIMPLE (default) the result is (theorically) a strictly + * if aFastMode is PM_STRICTLY_SIMPLE (default) the result is (theoretically) a strictly * simple polygon, but calculations can be really significantly time consuming */ void booleanOp( ClipperLib::ClipType aType, const SHAPE_POLY_SET& aOtherShape, @@ -1351,10 +1340,10 @@ private: const SHAPE_POLY_SET& aOtherShape, POLYGON_MODE aFastMode ); /** - * containsSingle function - * Checks whether the point aP is inside the aSubpolyIndex-th polygon of the polyset. If + * Check whether the point \a aP is inside the \a aSubpolyIndex-th polygon of the polyset. If * the points lies on an edge, the polygon is considered to contain it. - * @param aP is the VECTOR2I point whose position with respect to the inside of + * + * @param aP is the #VECTOR2I point whose position with respect to the inside of * the aSubpolyIndex-th polygon will be tested. * @param aSubpolyIndex is an integer specifying which polygon in the set has to be * checked. @@ -1362,14 +1351,13 @@ private: * @param aUseBBoxCaches gives faster performance when multiple calls are made with no * editing in between, but the caller MUST cache the bbox caches * before calling (via BuildBBoxCaches(), above) - * @return bool - true if aP is inside aSubpolyIndex-th polygon; false in any other - * case. + * @return true if \a aP is inside aSubpolyIndex-th polygon; false in any other case. */ bool containsSingle( const VECTOR2I& aP, int aSubpolyIndex, int aAccuracy, bool aUseBBoxCaches = false ) const; /** - * Operations ChamferPolygon and FilletPolygon are computed under the private chamferFillet + * Operation ChamferPolygon and FilletPolygon are computed under the private chamferFillet * method; this enum is defined to make the necessary distinction when calling this method * from the public ChamferPolygon and FilletPolygon methods. */ @@ -1380,9 +1368,8 @@ private: }; /** - * Function chamferFilletPolygon - * Returns the camfered or filleted version of the aIndex-th polygon in the set, depending - * on the aMode selected + * Return the chamfered or filleted version of the \a aIndex-th polygon in the set, depending + * on the \a aMode selected * @param aMode represent which action will be taken: CORNER_MODE::CHAMFERED will * return a chamfered version of the polygon, CORNER_MODE::FILLETED will * return a filleted version of the polygon. @@ -1391,12 +1378,12 @@ private: * @param aIndex is the index of the polygon that will be chamfered/filleted. * @param aErrorMax is the maximum allowable deviation of the polygon from the circle * if aMode = FILLETED. If aMode = CHAMFERED, it is unused. - * @return POLYGON - the chamfered/filleted version of the polygon. + * @return the chamfered/filleted version of the polygon. */ POLYGON chamferFilletPolygon( CORNER_MODE aMode, unsigned int aDistance, int aIndex, int aErrorMax ); - ///> Returns true if the polygon set has any holes that touch share a vertex. + ///< Return true if the polygon set has any holes that touch share a vertex. bool hasTouchingHoles( const POLYGON& aPoly ) const; MD5_HASH checksum() const; diff --git a/libs/kimath/include/geometry/shape_rect.h b/libs/kimath/include/geometry/shape_rect.h index 1d7ebc66aa..6633669569 100644 --- a/libs/kimath/include/geometry/shape_rect.h +++ b/libs/kimath/include/geometry/shape_rect.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -35,8 +37,7 @@ class SHAPE_RECT : public SHAPE { public: /** - * Constructor - * Creates an empty (0-sized) rectangle + * Create an empty (0-sized) rectangle. */ SHAPE_RECT() : SHAPE( SH_RECT ), @@ -45,8 +46,7 @@ public: {} /** - * Constructor - * Creates a rectangle defined by top-left corner (aX0, aY0), width aW and height aH. + * Create a rectangle defined by top-left corner (aX0, aY0), width aW and height aH. */ SHAPE_RECT( int aX0, int aY0, int aW, int aH ) : SHAPE( SH_RECT ), @@ -56,8 +56,7 @@ public: {} /** - * Constructor - * Creates a rectangle defined by top-left corner aP0, width aW and height aH. + * Create a rectangle defined by top-left corner aP0, width aW and height aH. */ SHAPE_RECT( const VECTOR2I& aP0, int aW, int aH ) : SHAPE( SH_RECT ), @@ -83,14 +82,12 @@ public: { BOX2I bbox( VECTOR2I( m_p0.x - aClearance, m_p0.y - aClearance ), VECTOR2I( m_w + 2 * aClearance, m_h + 2 * aClearance ) ); - //printf("bb : %s\n",bbox.Format().c_str()); return bbox; } /** - * Function Diagonal() + * Return length of the diagonal of the rectangle. * - * Returns length of the diagonal of the rectangle * @return diagonal length */ int Diagonal() const @@ -114,9 +111,7 @@ public: VECTOR2I* aLocation = nullptr ) const override; /** - * Function GetPosition() - * - * @return top-left corner of the rectangle + * @return the top left corner of the rectangle. */ const VECTOR2I& GetPosition() const { @@ -124,9 +119,7 @@ public: } /** - * Function GetSize() - * - * @return size of the rectangle + * @return the size of the rectangle. */ const VECTOR2I GetSize() const { @@ -134,9 +127,7 @@ public: } /** - * Function GetWidth() - * - * @return width of the rectangle + * @return the width of the rectangle. */ const int GetWidth() const { @@ -144,9 +135,7 @@ public: } /** - * Function GetHeight() - * - * @return height of the rectangle + * @return the height of the rectangle. */ const int GetHeight() const { @@ -159,12 +148,9 @@ public: } /** - * Function Rotate() * This function has limited utility for SHAPE_RECT as non-cartesian rotations will distort * the rectangle. If you might need to handle non-90º rotations then the SHAPE_RECT should * first be converted to a SHAPE_SIMPLE which can then be free-rotated. - * @param aAngle - * @param aCenter */ void Rotate( double aAngle, const VECTOR2I& aCenter = { 0, 0 } ) override { @@ -196,9 +182,9 @@ public: virtual const std::string Format( ) const override; private: - VECTOR2I m_p0; ///> Top-left corner - int m_w; ///> Width - int m_h; ///> Height + VECTOR2I m_p0; ///< Top-left corner + int m_w; ///< Width + int m_h; ///< Height }; #endif // __SHAPE_RECT_H diff --git a/libs/kimath/include/math/vector2d.h b/libs/kimath/include/math/vector2d.h index 128e366630..f2d64df16c 100644 --- a/libs/kimath/include/math/vector2d.h +++ b/libs/kimath/include/math/vector2d.h @@ -3,7 +3,7 @@ * * Copyright (C) 2010 Virtenio GmbH, Torsten Hueter, torsten.hueter virtenio.de * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2012 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2013 CERN * @author Tomasz Wlostowski * @@ -40,14 +40,13 @@ #endif /** - * VECTOR2_TRAITS - * traits class for VECTOR2. + * Traits class for VECTOR2. */ template struct VECTOR2_TRAITS { - ///> extended range/precision types used by operations involving multiple - ///> multiplications to prevent overflow. + ///< extended range/precision types used by operations involving multiple + ///< multiplications to prevent overflow. typedef T extended_type; }; @@ -64,8 +63,7 @@ template std::ostream& operator<<( std::ostream& aStream, const VECTOR2& aVector ); /** - * VECTOR2 - * defines a general 2D-vector/point. + * Define a general 2D-vector/point. * * This class uses templates to be universal. Several operators are provided to help * easy implementing of linear algebra equations. @@ -83,8 +81,6 @@ public: T x, y; - // Constructors - /// Construct a 2D-vector with x, y = 0 VECTOR2(); @@ -99,8 +95,7 @@ public: /// Construct a vector with given components x, y VECTOR2( T x, T y ); - /// Initializes a vector from another specialization. Beware of rouding - /// issues. + /// Initializes a vector from another specialization. Beware of rounding issues. template VECTOR2( const VECTOR2& aVec ) { @@ -115,8 +110,7 @@ public: y = aVec.y; } - /// Casts a vector to another specialized subclass. Beware of rouding - /// issues. + /// Cast a vector to another specialized subclass. Beware of rounding issues. template VECTOR2 operator()() const { @@ -124,81 +118,80 @@ public: } /** - * (wxPoint) - * implements the cast to wxPoint. - * @return wxPoint - the vector cast to wxPoint. + * Implement the cast to wxPoint. + * + * @return the vector cast to wxPoint. */ explicit operator wxPoint() const { return wxPoint( x, y ); } - /// Destructor // virtual ~VECTOR2(); /** - * Function Euclidean Norm - * computes the Euclidean norm of the vector, which is defined as sqrt(x ** 2 + y ** 2). + * Compute the Euclidean norm of the vector, which is defined as sqrt(x ** 2 + y ** 2). + * * It is used to calculate the length of the vector. + * * @return Scalar, the euclidean norm */ T EuclideanNorm() const; /** - * Function Squared Euclidean Norm - * computes the squared euclidean norm of the vector, which is defined as (x ** 2 + y ** 2). + * Compute the squared euclidean norm of the vector, which is defined as (x ** 2 + y ** 2). + * * It is used to calculate the length of the vector. + * * @return Scalar, the euclidean norm */ extended_type SquaredEuclideanNorm() const; /** - * Function Perpendicular - * computes the perpendicular vector + * Compute the perpendicular vector. + * * @return Perpendicular vector */ VECTOR2 Perpendicular() const; /** - * Function Resize - * returns a vector of the same direction, but length specified in aNewLength - * @param aNewLength: length of the rescaled vector - * @return rescaled vector + * Return a vector of the same direction, but length specified in \a aNewLength. + * + * @param aNewLength is the length of the rescaled vector. + * @return the rescaled vector. */ VECTOR2 Resize( T aNewLength ) const; /** - * Function Angle - * computes the angle of the vector - * @return vector angle, in radians + * Compute the angle of the vector. + * + * @return the vector angle in radians. */ double Angle() const; /** - * Function Rotate - * rotates the vector by a given angle + * Rotate the vector by a given angle. + * * @param aAngle rotation angle in radians * @return rotated vector */ VECTOR2 Rotate( double aAngle ) const; /** - * Function Format - * returns the vector formatted as a string + * Return the vector formatted as a string. + * * @return the formatted string */ const std::string Format() const; /** - * Function Cross() - * computes cross product of self with aVector + * Compute cross product of self with \a aVector. */ extended_type Cross( const VECTOR2& aVector ) const; /** - * Function Dot() - * computes dot product of self with aVector + * Compute dot product of self with \a aVector. */ extended_type Dot( const VECTOR2& aVector ) const; diff --git a/libs/kimath/include/math/vector3.h b/libs/kimath/include/math/vector3.h index 965ddf5d9d..6fef14c988 100644 --- a/libs/kimath/include/math/vector3.h +++ b/libs/kimath/include/math/vector3.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -21,14 +21,13 @@ #define VECTOR3_H_ /** - * VECTOR2_TRAITS - * traits class for VECTOR2. + * Traits class for VECTOR2. */ template struct VECTOR3_TRAITS { - ///> extended range/precision types used by operations involving multiple - ///> multiplications to prevent overflow. + ///< extended range/precision types used by operations involving multiple + ///< multiplications to prevent overflow. typedef T extended_type; }; @@ -40,8 +39,7 @@ struct VECTOR3_TRAITS /** - * VECTOR3 - * defines a general 3D-vector. + * Define a general 3D-vector. * * This class uses templates to be universal. Several operators are provided to help * easy implementing of linear algebra equations. @@ -65,7 +63,7 @@ public: /// Construct a vector with given components x, y VECTOR3( T x, T y, T z ); - /// Initializes a vector from another specialization. Beware of rouding + /// Initializes a vector from another specialization. Beware of rounding /// issues. template VECTOR3( const VECTOR3& aVec ) @@ -84,35 +82,33 @@ public: } /** - * Function Cross() - * computes cross product of self with aVector + * Compute cross product of self with \a aVector */ VECTOR3 Cross( const VECTOR3& aVector ) const; /** - * Function Dot() - * computes dot product of self with aVector + * Compute the dot product of self with \a aVector */ VECTOR3::extended_type Dot( const VECTOR3& aVector ) const; /** - * Function Euclidean Norm - * computes the Euclidean norm of the vector, which is defined as sqrt(x ** 2 + y ** 2). + * Compute the Euclidean norm of the vector, which is defined as sqrt(x ** 2 + y ** 2). + * * It is used to calculate the length of the vector. + * * @return Scalar, the euclidean norm */ T EuclideanNorm() const; /** - * Function Normalize() - * computes the normalized vector + * Compute the normalized vector. */ VECTOR3 Normalize(); - /// Equality operator + ///< Equality operator bool operator==( const VECTOR3& aVector ) const; - /// Not equality operator + ///< Not equality operator bool operator!=( const VECTOR3& aVector ) const; }; @@ -190,4 +186,4 @@ typedef VECTOR3 VECTOR3D; typedef VECTOR3 VECTOR3I; typedef VECTOR3 VECTOR3U; -#endif // VECTOR3_H_ \ No newline at end of file +#endif // VECTOR3_H_