From 6a39b81647978deae8cc800aec42e7fae89c9cb2 Mon Sep 17 00:00:00 2001 From: Wayne Stambaugh Date: Wed, 27 Jan 2021 17:15:38 -0500 Subject: [PATCH] Fix the last of broken Doxygen comment specifiers. --- eeschema/sim/ngspice.h | 2 +- eeschema/sim/sim_plot_panel.h | 2 +- kicad/tools/kicad_manager_actions.h | 9 +- kicad/tools/kicad_manager_control.cpp | 98 ++-- kicad/tools/kicad_manager_control.h | 11 +- pagelayout_editor/pl_draw_panel_gal.h | 12 +- pagelayout_editor/tools/pl_actions.h | 16 +- pagelayout_editor/tools/pl_drawing_tools.h | 6 +- pagelayout_editor/tools/pl_edit_tool.h | 22 +- pagelayout_editor/tools/pl_editor_control.h | 8 +- pagelayout_editor/tools/pl_point_editor.h | 22 +- pagelayout_editor/tools/pl_selection_tool.h | 47 +- pcbnew/autorouter/autoplace_tool.h | 6 +- pcbnew/board_connected_item.h | 102 ++-- .../dielectric_material.h | 56 ++- pcbnew/connectivity/connectivity_algo.h | 23 +- pcbnew/connectivity/connectivity_items.cpp | 3 +- pcbnew/connectivity/connectivity_items.h | 113 ++--- pcbnew/dialogs/dialog_board_statistics.h | 74 +-- pcbnew/dialogs/dialog_enum_pads.h | 13 +- pcbnew/dialogs/dialog_gencad_export_options.h | 12 +- pcbnew/dialogs/dialog_print_pcbnew.cpp | 14 +- pcbnew/dialogs/panel_setup_layers.h | 14 +- pcbnew/files.cpp | 88 ++-- pcbnew/footprint.h | 241 +++++----- pcbnew/footprint_edit_frame.h | 97 ++-- pcbnew/footprint_viewer_frame.h | 78 ++- pcbnew/footprint_wizard_frame.h | 132 +++-- pcbnew/fp_text.h | 22 +- pcbnew/import_gfx/graphics_import_mgr.h | 13 +- pcbnew/import_gfx/graphics_import_plugin.h | 5 +- pcbnew/import_gfx/graphics_importer.h | 39 +- pcbnew/import_gfx/graphics_importer_buffer.h | 12 +- pcbnew/import_gfx/graphics_importer_pcbnew.h | 36 +- pcbnew/microwave/microwave_tool.cpp | 15 +- pcbnew/microwave/microwave_tool.h | 40 +- pcbnew/netinfo.h | 152 +++--- pcbnew/netlist_reader/board_netlist_updater.h | 29 +- pcbnew/pad.h | 231 ++++----- pcbnew/pcb_base_edit_frame.h | 126 +++-- pcbnew/pcb_draw_panel_gal.h | 45 +- pcbnew/pcb_edit_frame.h | 453 ++++++++---------- pcbnew/pcb_painter.h | 51 +- pcbnew/pcbnew_printout.h | 16 +- pcbnew/plugins/eagle/eagle_plugin.h | 139 +++--- pcbnew/plugins/kicad/pcb_parser.h | 240 +++++----- pcbnew/plugins/legacy/legacy_plugin.h | 9 +- pcbnew/ratsnest/ratsnest_data.h | 54 +-- pcbnew/ratsnest/ratsnest_viewitem.h | 10 +- pcbnew/router/pns_algo_base.h | 25 +- pcbnew/router/pns_diff_pair_placer.h | 129 ++--- pcbnew/router/pns_dp_meander_placer.h | 39 +- pcbnew/router/pns_item.h | 57 +-- pcbnew/router/pns_joint.h | 37 +- pcbnew/router/pns_layerset.h | 11 +- pcbnew/router/pns_line.h | 74 ++- pcbnew/router/pns_line_placer.h | 205 +++----- pcbnew/router/pns_link_holder.h | 24 +- pcbnew/router/pns_meander.h | 264 +++++----- pcbnew/router/pns_meander_placer.h | 11 +- pcbnew/router/pns_meander_placer_base.h | 100 ++-- pcbnew/router/pns_node.cpp | 19 +- pcbnew/router/pns_node.h | 242 ++++------ pcbnew/router/pns_optimizer.h | 34 +- pcbnew/router/pns_routing_settings.h | 62 +-- pcbnew/router/router_tool.cpp | 21 +- pcbnew/tools/board_editor_control.h | 35 +- pcbnew/tools/board_inspection_tool.h | 38 +- pcbnew/tools/convert_tool.h | 44 +- pcbnew/tools/drawing_tool.h | 132 +++-- pcbnew/tools/drc_tool.h | 48 +- pcbnew/tools/edit_tool.h | 67 +-- pcbnew/tools/footprint_editor_control.h | 9 +- pcbnew/tools/global_edit_tool.h | 10 +- pcbnew/tools/group_tool.h | 19 +- pcbnew/tools/pad_tool.h | 25 +- pcbnew/tools/pcb_actions.h | 35 +- pcbnew/tools/pcb_control.h | 14 +- pcbnew/tools/pcb_editor_conditions.h | 36 +- pcbnew/tools/pcb_picker_tool.h | 34 +- pcbnew/tools/pcb_point_editor.h | 43 +- pcbnew/tools/pcb_selection_conditions.h | 32 +- pcbnew/tools/pcb_selection_tool.h | 145 +++--- pcbnew/tools/pcb_viewer_tools.h | 24 +- pcbnew/tools/placement_tool.h | 89 ++-- pcbnew/tools/position_relative_tool.h | 27 +- pcbnew/tools/zone_create_helper.h | 58 +-- pcbnew/tools/zone_filler_tool.h | 12 +- pcbnew/widgets/appearance_controls.h | 250 +++++----- utils/kicad2step/panel_kicad2step.h | 17 +- utils/kicad2step/pcb/base.h | 19 +- utils/kicad2step/pcb/kicadcurve.h | 5 +- 92 files changed, 2646 insertions(+), 3033 deletions(-) diff --git a/eeschema/sim/ngspice.h b/eeschema/sim/ngspice.h index 883c8eaf9e..037552ce93 100644 --- a/eeschema/sim/ngspice.h +++ b/eeschema/sim/ngspice.h @@ -61,7 +61,7 @@ public: ///< @copydoc SPICE_SIMULATOR::GetXAxis() std::string GetXAxis( SIM_TYPE aType ) const override; - ///> @copydoc SPICE_SIMULATOR::AllPlots() + ///< @copydoc SPICE_SIMULATOR::AllPlots() std::vector AllPlots() const override; ///< @copydoc SPICE_SIMULATOR::GetPlot() diff --git a/eeschema/sim/sim_plot_panel.h b/eeschema/sim/sim_plot_panel.h index 9163f894ca..61c4be83f2 100644 --- a/eeschema/sim/sim_plot_panel.h +++ b/eeschema/sim/sim_plot_panel.h @@ -298,7 +298,7 @@ private: ///< @return a new color from the palette wxColour generateColor(); - ///> @brief Constructs the plot axes for DC simulation plot + ///< @brief Construct the plot axes for DC simulation plot. void prepareDCAxes(); // Color index to get a new color from the palette diff --git a/kicad/tools/kicad_manager_actions.h b/kicad/tools/kicad_manager_actions.h index a6cf5a0bfe..c7a31d8184 100644 --- a/kicad/tools/kicad_manager_actions.h +++ b/kicad/tools/kicad_manager_actions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -32,9 +32,7 @@ class TOOL_EVENT; class TOOL_MANAGER; -/** - * KICAD_MANAGER_ACTIONS - * */ + class KICAD_MANAGER_ACTIONS : public ACTIONS { public: @@ -56,7 +54,7 @@ public: static TOOL_ACTION editOtherSch; static TOOL_ACTION editOtherPCB; - ///> @copydoc COMMON_ACTIONS::TranslateLegacyId() + ///< @copydoc COMMON_ACTIONS::TranslateLegacyId() virtual OPT TranslateLegacyId( int aId ) override { return OPT(); @@ -64,5 +62,4 @@ public: }; - #endif diff --git a/kicad/tools/kicad_manager_control.cpp b/kicad/tools/kicad_manager_control.cpp index d29dad4cd5..40a55e712f 100644 --- a/kicad/tools/kicad_manager_control.cpp +++ b/kicad/tools/kicad_manager_control.cpp @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -33,7 +33,8 @@ #include #include -///> Helper widget to select whether a new directory should be created for a project + +///< Helper widget to select whether a new directory should be created for a project. class DIR_CHECKBOX : public wxPanel { public: @@ -94,8 +95,7 @@ int KICAD_MANAGER_CONTROL::NewProject( const TOOL_EVENT& aEvent ) // wxFileName automatically extracts an extension. But if it isn't // a .pro extension, we should keep it as part of the filename - if( !pro.GetExt().IsEmpty() - && pro.GetExt().ToStdString() != ProjectFileExtension ) + if( !pro.GetExt().IsEmpty() && pro.GetExt().ToStdString() != ProjectFileExtension ) pro.SetName( pro.GetName() + wxT( "." ) + pro.GetExt() ); pro.SetExt( ProjectFileExtension ); // enforce extension @@ -322,17 +322,6 @@ int KICAD_MANAGER_CONTROL::CloseProject( const TOOL_EVENT& aEvent ) class SAVE_AS_TRAVERSER : public wxDirTraverser { -private: - KICAD_MANAGER_FRAME* m_frame; - - wxString m_projectDirPath; - wxString m_projectName; - wxString m_newProjectDirPath; - wxString m_newProjectName; - - wxFileName m_newProjectFile; - wxString m_errors; - public: SAVE_AS_TRAVERSER( KICAD_MANAGER_FRAME* aFrame, const wxString& aSrcProjectDirPath, @@ -380,27 +369,27 @@ public: KiCopyFile( aSrcFilePath, destFile.GetFullPath(), m_errors ); } else if( ext == "kicad_sch" - || ext == "kicad_sch-bak" - || ext == "sch" - || ext == "sch-bak" - || ext == "sym" - || ext == "lib" - || ext == "dcm" - || ext == "kicad_sym" - || ext == "net" - || destFile.GetName() == "sym-lib-table" ) + || ext == "kicad_sch-bak" + || ext == "sch" + || ext == "sch-bak" + || ext == "sym" + || ext == "lib" + || ext == "dcm" + || ext == "kicad_sym" + || ext == "net" + || destFile.GetName() == "sym-lib-table" ) { KIFACE* eeschema = m_frame->Kiway().KiFACE( KIWAY::FACE_SCH ); eeschema->SaveFileAs( m_projectDirPath, m_projectName, m_newProjectDirPath, m_newProjectName, aSrcFilePath, m_errors ); } else if( ext == "kicad_pcb" - || ext == "kicad_pcb-bak" - || ext == "brd" - || ext == "kicad_mod" - || ext == "mod" - || ext == "cmp" - || destFile.GetName() == "fp-lib-table" ) + || ext == "kicad_pcb-bak" + || ext == "brd" + || ext == "kicad_mod" + || ext == "mod" + || ext == "cmp" + || destFile.GetName() == "fp-lib-table" ) { KIFACE* pcbnew = m_frame->Kiway().KiFACE( KIWAY::FACE_PCB ); pcbnew->SaveFileAs( m_projectDirPath, m_projectName, m_newProjectDirPath, @@ -413,9 +402,9 @@ public: m_newProjectName, aSrcFilePath, m_errors ); } else if( ext == "gbr" - || ext == "gbrjob" - || ext == "drl" - || IsProtelExtension( ext ) ) + || ext == "gbrjob" + || ext == "drl" + || IsProtelExtension( ext ) ) { KIFACE* gerbview = m_frame->Kiway().KiFACE( KIWAY::FACE_GERBVIEW ); gerbview->SaveFileAs( m_projectDirPath, m_projectName, m_newProjectDirPath, @@ -487,6 +476,17 @@ public: wxString GetErrors() { return m_errors; } wxFileName GetNewProjectFile() { return m_newProjectFile; } + +private: + KICAD_MANAGER_FRAME* m_frame; + + wxString m_projectDirPath; + wxString m_projectName; + wxString m_newProjectDirPath; + wxString m_newProjectName; + + wxFileName m_newProjectFile; + wxString m_errors; }; @@ -648,7 +648,7 @@ int KICAD_MANAGER_CONTROL::ShowPlayer( const TOOL_EVENT& aEvent ) // Show the frame (and update widgets to set valid sizes), // after creating player and before calling OpenProjectFiles(). // Useful because loading a complex board and building its internal data can be - // time consumming + // time consuming player->Show( true ); wxSafeYield(); @@ -676,9 +676,6 @@ int KICAD_MANAGER_CONTROL::ShowPlayer( const TOOL_EVENT& aEvent ) class TERMINATE_HANDLER : public wxProcess { -private: - wxString m_appName; - public: TERMINATE_HANDLER( const wxString& appName ) : m_appName( appName ) @@ -686,9 +683,7 @@ public: void OnTerminate( int pid, int status ) override { - wxString msg = wxString::Format( _( "%s closed [pid=%d]\n" ), - m_appName, - pid ); + wxString msg = wxString::Format( _( "%s closed [pid=%d]\n" ), m_appName, pid ); wxWindow* window = wxWindow::FindWindowByName( KICAD_MANAGER_FRAME_NAME ); @@ -704,6 +699,9 @@ public: delete this; } + +private: + wxString m_appName; }; @@ -734,7 +732,8 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent ) if( aEvent.Parameter() ) params = *aEvent.Parameter(); - else if( ( aEvent.IsAction( &KICAD_MANAGER_ACTIONS::viewGerbers ) ) && m_frame->IsProjectActive() ) + else if( ( aEvent.IsAction( &KICAD_MANAGER_ACTIONS::viewGerbers ) ) + && m_frame->IsProjectActive() ) params = m_frame->Prj().GetProjectPath(); if( !params.empty() ) @@ -746,10 +745,7 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent ) if( pid > 0 ) { - wxString msg = wxString::Format( _( "%s %s opened [pid=%ld]\n" ), - execFile, - params, - pid ); + wxString msg = wxString::Format( _( "%s %s opened [pid=%ld]\n" ), execFile, params, pid ); m_frame->PrintMsg( msg ); #ifdef __WXMAC__ @@ -769,7 +765,8 @@ int KICAD_MANAGER_CONTROL::Execute( const TOOL_EVENT& aEvent ) void KICAD_MANAGER_CONTROL::setTransitions() { Go( &KICAD_MANAGER_CONTROL::NewProject, KICAD_MANAGER_ACTIONS::newProject.MakeEvent() ); - Go( &KICAD_MANAGER_CONTROL::NewFromTemplate, KICAD_MANAGER_ACTIONS::newFromTemplate.MakeEvent() ); + Go( &KICAD_MANAGER_CONTROL::NewFromTemplate, + KICAD_MANAGER_ACTIONS::newFromTemplate.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::OpenProject, KICAD_MANAGER_ACTIONS::openProject.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::CloseProject, KICAD_MANAGER_ACTIONS::closeProject.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::SaveProjectAs, ACTIONS::saveAs.MakeEvent() ); @@ -780,12 +777,15 @@ void KICAD_MANAGER_CONTROL::setTransitions() Go( &KICAD_MANAGER_CONTROL::ShowPlayer, KICAD_MANAGER_ACTIONS::editSchematic.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::ShowPlayer, KICAD_MANAGER_ACTIONS::editSymbols.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::ShowPlayer, KICAD_MANAGER_ACTIONS::editPCB.MakeEvent() ); - Go( &KICAD_MANAGER_CONTROL::ShowPlayer, KICAD_MANAGER_ACTIONS::editFootprints.MakeEvent() ); + Go( &KICAD_MANAGER_CONTROL::ShowPlayer, + KICAD_MANAGER_ACTIONS::editFootprints.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::viewGerbers.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::convertImage.MakeEvent() ); - Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::showCalculator.MakeEvent() ); + Go( &KICAD_MANAGER_CONTROL::Execute, + KICAD_MANAGER_ACTIONS::showCalculator.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::editWorksheet.MakeEvent() ); - Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::openTextEditor.MakeEvent() ); + Go( &KICAD_MANAGER_CONTROL::Execute, + KICAD_MANAGER_ACTIONS::openTextEditor.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::editOtherSch.MakeEvent() ); Go( &KICAD_MANAGER_CONTROL::Execute, KICAD_MANAGER_ACTIONS::editOtherPCB.MakeEvent() ); diff --git a/kicad/tools/kicad_manager_control.h b/kicad/tools/kicad_manager_control.h index a2209b6047..bf998ead06 100644 --- a/kicad/tools/kicad_manager_control.h +++ b/kicad/tools/kicad_manager_control.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,11 +33,8 @@ class KICAD_MANAGER_FRAME; /** - * KICAD_MANAGER_CONTROL - * - * Handles actions in the kicad manager frame. + * Handle actions in the kicad manager frame. */ - class KICAD_MANAGER_CONTROL : public TOOL_INTERACTIVE { public: @@ -59,11 +56,11 @@ public: int ShowPlayer( const TOOL_EVENT& aEvent ); int Execute( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: - ///> Pointer to the currently used edit/draw frame. + ///< Pointer to the currently used edit/draw frame. KICAD_MANAGER_FRAME* m_frame; // Mutex to allow only a single KiFace to load at one time (released when loaded) diff --git a/pagelayout_editor/pl_draw_panel_gal.h b/pagelayout_editor/pl_draw_panel_gal.h index 8cd723f414..546011b0ba 100644 --- a/pagelayout_editor/pl_draw_panel_gal.h +++ b/pagelayout_editor/pl_draw_panel_gal.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -38,7 +38,7 @@ public: virtual ~PL_DRAW_PANEL_GAL(); - ///> @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo() + ///< @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo() void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; /** @@ -46,17 +46,17 @@ public: */ void DisplayWorksheet(); - ///> @copydoc EDA_DRAW_PANEL_GAL::SwitchBackend + ///< @copydoc EDA_DRAW_PANEL_GAL::SwitchBackend bool SwitchBackend( GAL_TYPE aGalType ) override; - ///> @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer + ///< @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer virtual void SetTopLayer( int aLayer ) override; protected: - ///> Sets rendering targets & dependencies for layers. + ///< Set rendering targets & dependencies for layers. void setDefaultLayerDeps(); - ///> Currently used worksheet + ///< Currently used worksheet std::unique_ptr m_worksheet; std::unique_ptr m_pageDrawItem; diff --git a/pagelayout_editor/tools/pl_actions.h b/pagelayout_editor/tools/pl_actions.h index 5ee9889bf3..27a7db9fb0 100644 --- a/pagelayout_editor/tools/pl_actions.h +++ b/pagelayout_editor/tools/pl_actions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,9 +33,7 @@ class TOOL_EVENT; class TOOL_MANAGER; /** - * PL_ACTIONS - * - * Gathers all the actions that are shared by tools. The instance of PL_ACTIONS is created + * Gather all the actions that are shared by tools. The instance of PL_ACTIONS is created * inside of ACTION_MANAGER object that registers the actions. */ class PL_ACTIONS : public ACTIONS @@ -45,18 +43,18 @@ public: /// Activation of the selection tool static TOOL_ACTION selectionActivate; - /// Clears the current selection + /// Clear the current selection static TOOL_ACTION clearSelection; - /// Selects an item (specified as the event parameter). + /// Select an item (specified as the event parameter). static TOOL_ACTION addItemToSel; static TOOL_ACTION removeItemFromSel; - /// Selects a list of items (specified as the event parameter) + /// Select a list of items (specified as the event parameter) static TOOL_ACTION addItemsToSel; static TOOL_ACTION removeItemsFromSel; - /// Runs a selection menu to select from a list of items + /// Run a selection menu to select from a list of items static TOOL_ACTION selectionMenu; // Tools @@ -78,7 +76,7 @@ public: static TOOL_ACTION showInspector; static TOOL_ACTION previewSettings; - ///> @copydoc COMMON_ACTIONS::TranslateLegacyId() + ///< @copydoc COMMON_ACTIONS::TranslateLegacyId() virtual OPT TranslateLegacyId( int aId ) override { return OPT(); } }; diff --git a/pagelayout_editor/tools/pl_drawing_tools.h b/pagelayout_editor/tools/pl_drawing_tools.h index 869905e671..010d1ae96b 100644 --- a/pagelayout_editor/tools/pl_drawing_tools.h +++ b/pagelayout_editor/tools/pl_drawing_tools.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -34,8 +34,6 @@ class PL_SELECTION_TOOL; /** - * PL_DRAWING_TOOLS - * * Tool responsible for drawing/placing items (lines, rectangles, text, etc.) */ @@ -55,7 +53,7 @@ public: int PlaceItem( const TOOL_EVENT& aEvent ); private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: diff --git a/pagelayout_editor/tools/pl_edit_tool.h b/pagelayout_editor/tools/pl_edit_tool.h index 523021487c..9fd468cc31 100644 --- a/pagelayout_editor/tools/pl_edit_tool.h +++ b/pagelayout_editor/tools/pl_edit_tool.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -58,37 +58,35 @@ public: int ImportWorksheetContent( const TOOL_EVENT& aEvent ); /** - * Function DoDelete() - * - * Deletes the selected items, or the item under the cursor. + * Delete the selected items, or the item under the cursor. */ int DoDelete( const TOOL_EVENT& aEvent ); - ///> Runs the deletion tool. + ///< Run the deletion tool. int DeleteItemCursor( const TOOL_EVENT& aEvent ); private: void moveItem( WS_DATA_ITEM* aItem, VECTOR2I aDelta ); - ///> Returns the right modification point (e.g. for rotation), depending on the number of - ///> selected items. + ///< Return the right modification point (e.g. for rotation), depending on the number of + ///< selected items. bool updateModificationPoint( PL_SELECTION& aSelection ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: PL_EDITOR_FRAME* m_frame; PL_SELECTION_TOOL* m_selectionTool; - ///> Flag determining if anything is being dragged right now + ///< Flag determining if anything is being dragged right now. bool m_moveInProgress; - ///> Used for chaining commands + ///< Used for chaining commands. VECTOR2I m_moveOffset; - ///> Last cursor position (needed for getModificationPoint() to avoid changes - ///> of edit reference point). + ///< Last cursor position (needed for getModificationPoint() to avoid changes + ///< of edit reference point). VECTOR2I m_cursor; EDA_ITEM* m_pickerItem; diff --git a/pagelayout_editor/tools/pl_editor_control.h b/pagelayout_editor/tools/pl_editor_control.h index 6c14109e2e..cef0edafc4 100644 --- a/pagelayout_editor/tools/pl_editor_control.h +++ b/pagelayout_editor/tools/pl_editor_control.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -32,9 +32,7 @@ class PL_EDITOR_FRAME; /** - * PL_EDITOR_CONTROL - * - * Handles actions specific to the schematic editor in eeschema. + * Handle actions specific to the page layout editor. */ class PL_EDITOR_CONTROL : public wxEvtHandler, public TOOL_INTERACTIVE { @@ -70,7 +68,7 @@ public: int UpdateMessagePanel( const TOOL_EVENT& aEvent ); private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: diff --git a/pagelayout_editor/tools/pl_point_editor.h b/pagelayout_editor/tools/pl_point_editor.h index 5fa08240bd..5844126f81 100644 --- a/pagelayout_editor/tools/pl_point_editor.h +++ b/pagelayout_editor/tools/pl_point_editor.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -34,8 +34,6 @@ class PL_SELECTION_TOOL; class PL_EDITOR_FRAME; /** - * PL_POINT_EDITOR - * * Tool that displays edit points allowing to modify items by dragging the points. */ class PL_POINT_EDITOR : public TOOL_INTERACTIVE @@ -52,28 +50,28 @@ public: int Main( const TOOL_EVENT& aEvent ); /** - * Indicates the cursor is over an edit point. Used to coordinate cursor shapes with + * Indicate the cursor is over an edit point. Used to coordinate cursor shapes with * other tools. */ bool HasPoint() { return m_editedPoint != nullptr; } - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: - ///> Updates item's points with edit points. + ///< Update item's points with edit points. void updateItem() const; - ///> Updates edit points with item's points. + ///< Update edit points with item's points. void updatePoints(); - ///> Updates which point is being edited. + ///< Update which point is being edited. void updateEditedPoint( const TOOL_EVENT& aEvent ); - ///> Sets the current point being edited. NULL means none. + ///< Set the current point being edited. NULL means none. void setEditedPoint( EDIT_POINT* aPoint ); - ///> Returns true if aPoint is the currently modified point. + ///< Return true if aPoint is the currently modified point. inline bool isModified( const EDIT_POINT& aPoint ) const { return m_editedPoint == &aPoint; @@ -96,10 +94,10 @@ private: PL_EDITOR_FRAME* m_frame; PL_SELECTION_TOOL* m_selectionTool; - ///> Currently edited point, NULL if there is none. + ///< Currently edited point, NULL if there is none. EDIT_POINT* m_editedPoint; - ///> Currently available edit points. + ///< Currently available edit points. std::shared_ptr m_editPoints; }; diff --git a/pagelayout_editor/tools/pl_selection_tool.h b/pagelayout_editor/tools/pl_selection_tool.h index 10b25a5f24..2f795c8b92 100644 --- a/pagelayout_editor/tools/pl_selection_tool.h +++ b/pagelayout_editor/tools/pl_selection_tool.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -54,35 +54,29 @@ public: int UpdateMenu( const TOOL_EVENT& aEvent ); /** - * Function Main() - * * The main loop. */ int Main( const TOOL_EVENT& aEvent ); /** - * Function GetSelection() - * - * Returns the set of currently selected items. + * Return the set of currently selected items. */ PL_SELECTION& GetSelection(); /** - * Function RequestSelection() - * - * Returns either an existing selection (filtered), or the selection at the current + * Return either an existing selection (filtered), or the selection at the current * cursor if the existing selection is empty. */ PL_SELECTION& RequestSelection(); /** - * Function selectPoint() - * Selects an item pointed by the parameter aWhere. If there is more than one item at that + * Select an item pointed by the parameter aWhere. If there is more than one item at that * place, there is a menu displayed that allows one to choose the item. * * @param aWhere is the place where the item should be selected. * @param aSelectionCancelledFlag allows the function to inform its caller that a selection - * was cancelled (for instance, by clicking outside of the disambiguation menu). + * was canceled (for instance, by clicking outside of the + * disambiguation menu). */ void SelectPoint( const VECTOR2I& aWhere, bool* aSelectionCancelledFlag = nullptr ); @@ -109,21 +103,18 @@ public: void RebuildSelection(); /** - * Function SelectionMenu() * Shows a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single * item. * - * NOTE: this routine DOES NOT modify the selection. + * @note This routine **does not** modify the selection. */ int SelectionMenu( const TOOL_EVENT& aEvent ); private: /** - * Function selectMultiple() - * Handles drawing a selection box that allows one to select many items at - * the same time. + * Handle drawing a selection box that allows one to select many items at the same time. * - * @return true if the function was cancelled (i.e. CancelEvent was received). + * @return true if the function was canceled (i.e. CancelEvent was received). */ bool selectMultiple(); @@ -134,15 +125,15 @@ private: void guessSelectionCandidates( COLLECTOR& collector, const VECTOR2I& aWhere ); /** - * Allows the selection of a single item from a list via pop-up menu. The items are + * Allow the selection of a single item from a list via pop-up menu. The items are * highlighted on the canvas when hovered in the menu. The collector is trimmed to * the picked item. - * @return true if an item was picked + * + * @return true if an item was picked. */ bool doSelectionMenu( COLLECTOR* aItems ); /** - * Function select() * Takes necessary action mark an item as selected. * * @param aItem is an item to be selected. @@ -150,16 +141,15 @@ private: void select( EDA_ITEM* aItem ); /** - * Function unselect() - * Takes necessary action mark an item as unselected. + * Take necessary action mark an item as unselected. * * @param aItem is an item to be unselected. */ void unselect( EDA_ITEM* aItem ); /** - * Function highlight() - * Highlights the item visually. + * Highlight the item visually. + * * @param aItem is an item to be be highlighted. * @param aHighlightMode should be either SELECTED or BRIGHTENED * @param aGroup is the group to add the item to in the BRIGHTENED mode. @@ -167,8 +157,8 @@ private: void highlight( EDA_ITEM* aItem, int aHighlightMode, PL_SELECTION* aGroup = nullptr ); /** - * Function unhighlight() - * Unhighlights the item visually. + * Unhighlight the item visually. + * * @param aItem is an item to be be highlighted. * @param aHighlightMode should be either SELECTED or BRIGHTENED * @param aGroup is the group to remove the item from. @@ -176,12 +166,11 @@ private: void unhighlight( EDA_ITEM* aItem, int aHighlightMode, PL_SELECTION* aGroup = nullptr ); /** - * Function selectionContains() * @return True if the given point is contained in any of selected items' bounding box. */ bool selectionContains( const VECTOR2I& aPoint ) const; - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: diff --git a/pcbnew/autorouter/autoplace_tool.h b/pcbnew/autorouter/autoplace_tool.h index 175e275394..2958dd9db8 100644 --- a/pcbnew/autorouter/autoplace_tool.h +++ b/pcbnew/autorouter/autoplace_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -28,8 +28,6 @@ /** - * AUTOPLACE_TOOL - * * Tool responsible for automagic placement of components. */ class AUTOPLACE_TOOL : public PCB_TOOL_BASE @@ -38,7 +36,7 @@ public: AUTOPLACE_TOOL(); ~AUTOPLACE_TOOL(); - ///> Bind handlers to corresponding TOOL_ACTIONs + ///< Bind handlers to corresponding TOOL_ACTIONs. void setTransitions() override; private: diff --git a/pcbnew/board_connected_item.h b/pcbnew/board_connected_item.h index 332463b977..2b45f7663f 100644 --- a/pcbnew/board_connected_item.h +++ b/pcbnew/board_connected_item.h @@ -3,7 +3,7 @@ * * Copyright (C) 2012 Jean-Pierre Charras, jean-pierre.charras@ujf-grenoble.fr * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 1992-2012 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,11 +35,8 @@ class TRACK; class PAD; /** - * BOARD_CONNECTED_ITEM - * is a base class derived from BOARD_ITEM for items that can be connected - * and have a net, a netname, a clearance ... - * mainly: tracks, pads and zones - * Handle connection info + * A base class derived from #BOARD_ITEM for items that can be connected and have a net, a + * netname, a clearance ... */ class BOARD_CONNECTED_ITEM : public BOARD_ITEM { @@ -68,15 +65,14 @@ public: } } - ///> @copydoc BOARD_ITEM::IsConnected() + ///< @copydoc BOARD_ITEM::IsConnected() bool IsConnected() const override { return true; } /** - * Function GetNet - * Returns NET_INFO object for a given item. + * Return #NET_INFO object for a given item. */ NETINFO_ITEM* GetNet() const { @@ -84,8 +80,7 @@ public: } /** - * Function SetNet - * Sets a NET_INFO object for the item. + * Set a NET_INFO object for the item. */ void SetNet( NETINFO_ITEM* aNetInfo ) { @@ -93,8 +88,7 @@ public: } /** - * Function GetNetCode - * @return int - the net code. + * @return the net code. */ int GetNetCode() const { @@ -102,13 +96,15 @@ public: } /** - * Sets net using a net code. - * @param aNetCode is a net code for the new net. It has to exist in NETINFO_LIST held by BOARD. - * @param aNoAssert if true, do not assert that the net exists. - * Otherwise, item is assigned to the unconnected net. + * Set net using a net code. + * + * @note Pads not on copper layers will have their net code always set to 0 (not connected). + * + * @param aNetCode is a net code for the new net. It has to exist in #NETINFO_LIST held + * by #BOARD. + * @param aNoAssert if true, do not assert that the net exists. Otherwise, item is assigned + * to the unconnected net. * @return true on success, false if the net did not exist - * Note also items (in fact pads) not on copper layers will have - * their net code always set to 0 (not connected) */ bool SetNetCode( int aNetCode, bool aNoAssert ); @@ -118,8 +114,7 @@ public: } /** - * Function GetNetname - * @return wxString - the full netname + * @return the full netname. */ wxString GetNetname() const { @@ -127,15 +122,13 @@ public: } /** - * Function GetNetnameMsg - * @return wxString - the full netname or "" in square braces, followed by - * "(Not Found)" if the netcode is undefined. + * @return the full netname or "" in square braces, followed by "(Not Found)" if the + * netcode is undefined. */ wxString GetNetnameMsg() const; /** - * Function GetShortNetname - * @return wxString - the short netname + * @return the short netname. */ wxString GetShortNetname() const { @@ -143,56 +136,54 @@ public: } /** - * Function GetClearance - * returns an item's "own" clearance in internal units. - * @param aLayer the layer in question - * @param aSource [out] optionally reports the source as a user-readable string - * @return int - the clearance in internal units. + * Return an item's "own" clearance in internal units. + * + * @param aLayer the layer in question. + * @param aSource [out] optionally reports the source as a user-readable string. + * @return the clearance in internal units. */ virtual int GetOwnClearance( PCB_LAYER_ID aLayer, wxString* aSource = nullptr ) const; /** - * Function GetLocalClearanceOverrides - * returns any local clearance overrides set in the "classic" (ie: pre-rule) system. - * @param aSource [out] optionally reports the source as a user-readable string - * @return int - the clearance in internal units. + * Return any local clearance overrides set in the "classic" (ie: pre-rule) system. + * + * @param aSource [out] optionally reports the source as a user-readable string. + * @return the clearance in internal units. */ virtual int GetLocalClearanceOverrides( wxString* aSource ) const { return 0; } /** - * Function GetLocalClearance - * returns any local clearances set in the "classic" (ie: pre-rule) system. These are - * things like zone clearance which are NOT an override. - * @param aSource [out] optionally reports the source as a user-readable string - * @return int - the clearance in internal units. + * Return any local clearances set in the "classic" (ie: pre-rule) system. These are + * things like zone clearance which are **not** an override. + * + * @param aSource [out] optionally reports the source as a user readable string. + * @return the clearance in internal units. */ virtual int GetLocalClearance( wxString* aSource ) const { return 0; } /** - * Function GetNetClassPtr - * returns the NETCLASS for this item. + * Return the #NETCLASS for this item. * - * Note: do NOT return a std::shared_ptr from this. It is used heavily in DRC, and the - * std::shared_ptr stuff shows up large in performance profiling. + * @note Do **not** return a std::shared_ptr from this. It is used heavily in DRC, and the + * std::shared_ptr stuff shows up large in performance profiling. */ virtual NETCLASS* GetNetClass() const; /** - * Function GetEffectiveNetclass - * returns the NETCLASS for this item, or the default netclass if none is defined. + * Return the NETCLASS for this item, or the default netclass if none is defined. * - * Note: do NOT return a std::shared_ptr from this. It is used heavily in DRC, and the - * std::shared_ptr stuff shows up large in performance profiling. + * @note Do **not** return a std::shared_ptr from this. It is used heavily in DRC, and the + * std::shared_ptr stuff shows up large in performance profiling. */ virtual NETCLASS* GetEffectiveNetclass() const; /** - * Function GetNetClassName - * returns a pointer to the netclass of the zone. - * If the net is not found (can happen when a netlist is reread, - * and the net name does not exist, return the default net class - * (should not return a null pointer). - * @return the Net Class name of this item + * Returns the netclass of the zone. + * + * If the net is not found (can happen when a netlist is reread) and the net name does not + * exist, return the default net class (should not return a null pointer). + * + * @return the net class name of this item. */ virtual wxString GetNetClassName() const; @@ -207,11 +198,10 @@ public: } protected: - /// Stores all informations about the net that item belongs to + /// Store all information about the net that item belongs to. NETINFO_ITEM* m_netinfo; private: - bool m_localRatsnestVisible; }; diff --git a/pcbnew/board_stackup_manager/dielectric_material.h b/pcbnew/board_stackup_manager/dielectric_material.h index 63f158e6d3..f058c6351f 100644 --- a/pcbnew/board_stackup_manager/dielectric_material.h +++ b/pcbnew/board_stackup_manager/dielectric_material.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 2009-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2009-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,7 +33,7 @@ #include -// A class to handle substrates prms in gerber job file and dialog +// A class to handle substrates prms in gerber job file and dialog. struct DIELECTRIC_SUBSTRATE { wxString m_Name; // the name (in job file) of material @@ -44,10 +44,10 @@ struct DIELECTRIC_SUBSTRATE }; -// A struct to handle a list of substrates prms in gerber job file and dialogs +// Handle a list of substrates prms in gerber job file and dialogs class DIELECTRIC_SUBSTRATE_LIST { - ///> The list of available substrates. It contians at least predefined substrates + ///< The list of available substrates. It contains at least predefined substrates std::vector m_substrateList; public: @@ -58,10 +58,9 @@ public: DL_MATERIAL_SILKSCREEN }; - /** Ctor - * @param aForDielectric = - * DL_MATERIAL_DIELECTRIC to build a dielectric material list - * DL_MATERIAL_SOLDERMASK to build a solder mask material list + /** + * @param aForDielectric set to #DL_MATERIAL_DIELECTRIC to build a dielectric material list + * or #DL_MATERIAL_SOLDERMASK to build a solder mask material list. */ DIELECTRIC_SUBSTRATE_LIST( DL_MATERIAL_LIST_TYPE aListType); @@ -71,38 +70,45 @@ public: int GetCount() { return (int)m_substrateList.size(); } /** - * @return the substrate in list of index aIdx - * if incorrect return nullptr + * @return the substrate in list of index \a aIdx if incorrect return nullptr. + * * @param aIdx is the index in substrate list. */ DIELECTRIC_SUBSTRATE* GetSubstrate( int aIdx ); /** - * @return the substrate in list of name aName - * if not found return nullptr + * The comparison is case insensitive. + * * @param aName is the name of the substrate in substrate list. - * the comparison is case insensitve + * @return the substrate in list of name \a aName if not found return nullptr. */ DIELECTRIC_SUBSTRATE* GetSubstrate( const wxString& aName ); - /** Find a item in list similar to aItem - * @param aItem is the item to match - * @return the index of similar item in list or -1 if not found - * the comparison is for the name case insensitive, and EpsilonR and LossTg must match + /** + * Find a item in list similar to \a aItem. + * + * The comparison is for the name case insensitive, and EpsilonR and LossTg must match. + * + * @param aItem is the item to match. + * @return the index of similar item in list or -1 if not found. */ int FindSubstrate( DIELECTRIC_SUBSTRATE* aItem ); - /** Find a item in list having the sapme parameters - * @param aName is the name to match (case insensitive) - * @param aEpsilonR is the Repaltive Permeatbility to match - * @param aLossTg is the loss tangent to match - * @return the index of similar item in list or -1 if not found + /** + * Find a item in list having the same parameters. + * + * @param aName is the name to match (case insensitive). + * @param aEpsilonR is the relative permeability to match. + * @param aLossTg is the loss tangent to match. + * @return the index of similar item in list or -1 if not found. */ int FindSubstrate( const wxString& aName, double aEpsilonR, double aLossTg ); - /** Append a item in list similar to aItem - * @param aItem is the item to append - * @return the index of the new item in list + /** + * Append a item in list similar to \a aItem. + * + * @param aItem is the item to append. + * @return the index of the new item in list. */ int AppendSubstrate( DIELECTRIC_SUBSTRATE& aItem ) { diff --git a/pcbnew/connectivity/connectivity_algo.h b/pcbnew/connectivity/connectivity_algo.h index 232b2680f7..407a1f60b1 100644 --- a/pcbnew/connectivity/connectivity_algo.h +++ b/pcbnew/connectivity/connectivity_algo.h @@ -2,7 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN - * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * @author Tomasz Wlostowski * @@ -68,9 +69,10 @@ public: {} /** - * This sort operator provides a sort-by-weight for the ratsnest operation - * @param aOther Other edge to compare - * @return true if our weight is smaller than the other weight + * This sort operator provides a sort-by-weight for the ratsnest operation. + * + * @param aOther the other edge to compare. + * @return true if our weight is smaller than the other weight. */ bool operator<( CN_EDGE aOther ) const { @@ -155,7 +157,6 @@ public: }; private: - CN_LIST m_itemList; std::unordered_map m_itemMap; @@ -180,7 +181,6 @@ private: void markItemNetAsDirty( const BOARD_ITEM* aItem ); public: - CN_CONNECTIVITY_ALGO() {} ~CN_CONNECTIVITY_ALGO() { Clear(); } @@ -281,13 +281,9 @@ public: void SetProgressReporter( PROGRESS_REPORTER* aReporter ); }; -/** - * Struct CN_VISTOR - **/ -class CN_VISITOR { - +class CN_VISITOR +{ public: - CN_VISITOR( CN_ITEM* aItem ) : m_item( aItem ) {} @@ -295,12 +291,11 @@ public: bool operator()( CN_ITEM* aCandidate ); protected: - void checkZoneItemConnection( CN_ZONE_LAYER* aZoneLayer, CN_ITEM* aItem ); void checkZoneZoneConnection( CN_ZONE_LAYER* aZoneLayerA, CN_ZONE_LAYER* aZoneLayerB ); - ///> the item we are looking for connections to + ///< The item we are looking for connections to. CN_ITEM* m_item; }; diff --git a/pcbnew/connectivity/connectivity_items.cpp b/pcbnew/connectivity/connectivity_items.cpp index 60f4ad0df1..b480466ae4 100644 --- a/pcbnew/connectivity/connectivity_items.cpp +++ b/pcbnew/connectivity/connectivity_items.cpp @@ -1,8 +1,9 @@ + /* * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016-2018 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Tomasz Wlostowski * diff --git a/pcbnew/connectivity/connectivity_items.h b/pcbnew/connectivity/connectivity_items.h index 970acf6605..82b733cedc 100644 --- a/pcbnew/connectivity/connectivity_items.h +++ b/pcbnew/connectivity/connectivity_items.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN - * Copyright (C) 2018-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. * * @author Maciej Suminski * @author Tomasz Wlostowski @@ -91,25 +91,25 @@ public: return ( m_pos - aSecond.Pos() ).EuclideanNorm(); } - /// Returns tag, common identifier for connected nodes + ///< Return tag, common identifier for connected nodes. inline int GetTag() const { return m_tag; } - /// Sets tag, common identifier for connected nodes + ///< Set tag, common identifier for connected nodes. inline void SetTag( int aTag ) { m_tag = aTag; } - /// Decides whether this node can be a ratsnest line target + ///< Decide whether this node can be a ratsnest line target. inline void SetNoLine( bool aEnable ) { m_noline = aEnable; } - /// Returns true if this node can be a target for ratsnest lines + ///< Return true if this node can be a target for ratsnest lines. inline const bool& GetNoLine() const { return m_noline; @@ -126,18 +126,16 @@ public: } /** - * has meaning only for tracks and vias. - * @return true if this anchor is dangling - * The anchor point is dangling if the parent is a track - * and this anchor point is not connected to another item - * ( track, vas pad or zone) or if the parent is a via and this anchor point - * is connected to only one track and not to another item + * The anchor point is dangling if the parent is a track and this anchor point is not + * connected to another item ( track, vas pad or zone) or if the parent is a via and + * this anchor point is connected to only one track and not to another item. + * + * @return true if this anchor is dangling. */ bool IsDangling() const; /** - * has meaning only for tracks and vias. - * @return the count of items connected to this anchor + * @return the count of tracks and vias connected to this anchor. */ int ConnectedItemsCount() const; @@ -145,19 +143,19 @@ public: static const int TAG_UNCONNECTED = -1; private: - /// Position of the anchor + ///< Position of the anchor. VECTOR2I m_pos; - /// Item owning the anchor + ///< Item owning the anchor. CN_ITEM* m_item = nullptr; - /// Tag for quick connection resolution + ///< Tag for quick connection resolution. int m_tag = -1; - /// Whether it the node can be a target for ratsnest lines + ///< Whether it the node can be a target for ratsnest lines. bool m_noline = false; - /// Cluster to which the anchor belongs + ///< Cluster to which the anchor belongs. std::shared_ptr m_cluster; }; @@ -172,26 +170,6 @@ class CN_ITEM public: using CONNECTED_ITEMS = std::vector; -private: - BOARD_CONNECTED_ITEM* m_parent; - - CONNECTED_ITEMS m_connected; ///> list of items physically connected (touching) - CN_ANCHORS m_anchors; - - bool m_canChangeNet; ///> can the net propagator modify the netcode? - - bool m_visited; ///> visited flag for the BFS scan - bool m_valid; ///> used to identify garbage items (we use lazy removal) - - std::mutex m_listLock; ///> mutex protecting this item's connected_items set to - ///> allow parallel connection threads -protected: - bool m_dirty; ///> used to identify recently added item not yet - ///> scanned into the connectivity search - LAYER_RANGE m_layers; ///> layer range over which the item exists - BOX2I m_bbox; ///> bounding box for the item - -public: void Dump(); CN_ITEM( BOARD_CONNECTED_ITEM* aParent, bool aCanChangeNet, int aAnchorCount = 2 ) @@ -222,9 +200,7 @@ public: bool Dirty() const { return m_dirty; } /** - * Function SetLayers() - * - * Sets the layers spanned by the item to aLayers. + * Set the layers spanned by the item to aLayers. */ void SetLayers( const LAYER_RANGE& aLayers ) { @@ -232,9 +208,7 @@ public: } /** - * Function SetLayer() - * - * Sets the layers spanned by the item to a single layer aLayer. + * Set the layers spanned by the item to a single layer aLayer. */ void SetLayer( int aLayer ) { @@ -242,9 +216,7 @@ public: } /** - * Function Layers() - * - * Returns the contiguous set of layers spanned by the item. + * Return the contiguous set of layers spanned by the item. */ const LAYER_RANGE& Layers() const { @@ -252,9 +224,7 @@ public: } /** - * Function Layer() - * - * Returns the item's layer, for single-layered items only. + * Return the item's layer, for single-layered items only. */ virtual int Layer() const { @@ -305,6 +275,25 @@ public: { return ( !m_parent || !m_valid ) ? -1 : m_parent->GetNetCode(); } + ///< allow parallel connection threads +protected: + bool m_dirty; ///< used to identify recently added item not yet + ///< scanned into the connectivity search + LAYER_RANGE m_layers; ///< layer range over which the item exists + BOX2I m_bbox; ///< bounding box for the item + +private: + BOARD_CONNECTED_ITEM* m_parent; + + CONNECTED_ITEMS m_connected; ///< list of items physically connected (touching) + CN_ANCHORS m_anchors; + + bool m_canChangeNet; ///< can the net propagator modify the netcode? + + bool m_visited; ///< visited flag for the BFS scan + bool m_valid; ///< used to identify garbage items (we use lazy removal) + + std::mutex m_listLock; ///< mutex protecting this item's connected_items set to }; typedef std::shared_ptr CN_ITEM_PTR; @@ -366,12 +355,6 @@ private: class CN_LIST { -private: - bool m_dirty; - bool m_hasInvalid; - - CN_RTREE m_index; - protected: std::vector m_items; @@ -457,14 +440,20 @@ public: CN_ITEM* Add( VIA* via ); const std::vector Add( ZONE* zone, PCB_LAYER_ID aLayer ); + +private: + bool m_dirty; + bool m_hasInvalid; + + CN_RTREE m_index; }; class CN_CLUSTER { private: - bool m_conflicting = false; - int m_originNet = 0; - CN_ITEM* m_originPad = nullptr; + bool m_conflicting; + int m_originNet; + CN_ITEM* m_originPad; std::vector m_items; public: @@ -476,9 +465,9 @@ public: wxString OriginNetName() const; - bool Contains( const CN_ITEM* aItem ); - bool Contains( const BOARD_CONNECTED_ITEM* aItem ); - void Dump(); + bool Contains( const CN_ITEM* aItem ); + bool Contains( const BOARD_CONNECTED_ITEM* aItem ); + void Dump(); int Size() const { return m_items.size(); } diff --git a/pcbnew/dialogs/dialog_board_statistics.h b/pcbnew/dialogs/dialog_board_statistics.h index d6ee5a00ff..af81abaa32 100644 --- a/pcbnew/dialogs/dialog_board_statistics.h +++ b/pcbnew/dialogs/dialog_board_statistics.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 Alexander Shuklin, jasuramme@gmail.com - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -39,15 +39,13 @@ #include /** - * DIALOG_BOARD_STATISTIC - * * Dialog to show common board info. */ class DIALOG_BOARD_STATISTICS : public DIALOG_BOARD_STATISTICS_BASE { public: /** - * Struct to hold type information, which will be shown in dialog. + * Type information, which will be shown in dialog. */ template struct typeContainer_t @@ -58,6 +56,7 @@ public: qty( 0 ) { } + T attribute; wxString title; int qty; @@ -67,9 +66,8 @@ public: using viasType_t = typeContainer_t; /** - * Struct holds information about component type (such as SMD, THT, - * Virtual and so on), which will be shown in the dialog. Holds both - * front and bottom components quantities + * Footprint attributes (such as SMD, THT, Virtual and so on), which will be shown in the + * dialog. Holds both front and bottom components quantities. */ struct componentsType_t { @@ -80,6 +78,7 @@ public: backSideQty( 0 ) { } + FOOTPRINT_ATTR_T attribute; wxString title; int frontSideQty; @@ -99,6 +98,7 @@ public: COL_START_LAYER, COL_STOP_LAYER }; + drillType_t( int aXSize, int aYSize, PAD_DRILL_SHAPE_T aShape, bool aIsPlated, bool aIsPad, PCB_LAYER_ID aStartLayer, PCB_LAYER_ID aStopLayer, int aQty = 0 ) : xSize( aXSize ), @@ -111,12 +111,14 @@ public: qty( aQty ) { } + bool operator==( const drillType_t& other ) { return xSize == other.xSize && ySize == other.ySize && shape == other.shape && isPlated == other.isPlated && isPad == other.isPad && startLayer == other.startLayer && stopLayer == other.stopLayer; } + struct COMPARE { COMPARE( COL_ID aColId, bool aAscending ) : colId( aColId ), ascending( aAscending ) @@ -146,13 +148,16 @@ public: return false; } + bool compareDrillParameters( int aLeft, int aRight ) { return ascending ? aLeft < aRight : aLeft > aRight; } + COL_ID colId; bool ascending; }; + int xSize; int ySize; PAD_DRILL_SHAPE_T shape; @@ -171,44 +176,24 @@ public: DIALOG_BOARD_STATISTICS( PCB_EDIT_FRAME* aParentFrame ); ~DIALOG_BOARD_STATISTICS(); - ///> Get data from the PCB board and print it to dialog + ///< Get data from the PCB board and print it to dialog bool TransferDataToWindow() override; private: - PCB_EDIT_FRAME* m_parentFrame; - int m_boardWidth; - int m_boardHeight; - double m_boardArea; - - ///> Shows if board outline properly defined - bool m_hasOutline; - - ///> Holds all components types to be shown in the dialog - componentsTypeList_t m_componentsTypes; - - ///> Holds all pads types to be shown in the dialog - padsTypeList_t m_padsTypes; - - ///> Holds all vias types to be shown in the dialog - viasTypeList_t m_viasTypes; - - ///> Holds all drill hole types to be shown in the dialog - drillTypeList_t m_drillTypes; - - ///> Function to fill up all items types to be shown in the dialog. + ///< Function to fill up all items types to be shown in the dialog. void refreshItemsTypes(); - ///> Gets data from board + ///< Get data from board. void getDataFromPCB(); - ///> Applies data to dialog widgets + ///< Apply data to dialog widgets. void updateWidets(); - ///> Updates drills grid + ///< Update drills grid. void updateDrillGrid(); - ///> Prints grid to string in tabular format + ///< Print grid to string in tabular format. void printGridToStringAsTable( wxGrid* aGrid, wxString& aStr, bool aUseRowLabels, bool aUseColLabels, bool aUseFirstColAsLabel ); @@ -216,12 +201,33 @@ private: void checkboxClicked( wxCommandEvent& aEvent ) override; - ///> Save board statistics to a file + ///< Save board statistics to a file void saveReportClicked( wxCommandEvent& aEvent ) override; void drillGridSize( wxSizeEvent& aEvent ) override; void drillGridSort( wxGridEvent& aEvent ); + + PCB_EDIT_FRAME* m_parentFrame; + + int m_boardWidth; + int m_boardHeight; + double m_boardArea; + + ///< Show if board outline properly defined. + bool m_hasOutline; + + ///< Hold all components types to be shown in the dialog. + componentsTypeList_t m_componentsTypes; + + ///< Hold all pads types to be shown in the dialog. + padsTypeList_t m_padsTypes; + + ///< Hold all vias types to be shown in the dialog. + viasTypeList_t m_viasTypes; + + ///< Hold all drill hole types to be shown in the dialog. + drillTypeList_t m_drillTypes; }; #endif // __DIALOG_BOARD_STATISTICS_H diff --git a/pcbnew/dialogs/dialog_enum_pads.h b/pcbnew/dialogs/dialog_enum_pads.h index 188c7328dc..bdc145f570 100644 --- a/pcbnew/dialogs/dialog_enum_pads.h +++ b/pcbnew/dialogs/dialog_enum_pads.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -26,23 +28,20 @@ #define __dialog_enum_pads__ /** -@file -Subclass of DIALOG_ENUM_PADS_BASE, which is generated by wxFormBuilder. -*/ + * @file Subclass of DIALOG_ENUM_PADS_BASE which is generated by wxFormBuilder. + */ #include "dialog_enum_pads_base.h" -/** Implementing DIALOG_ENUM_PADS_BASE */ class DIALOG_ENUM_PADS : public DIALOG_ENUM_PADS_BASE { public: - /** Constructor */ DIALOG_ENUM_PADS( wxWindow* parent ); - ///> Returns the starting number that is going to be used for the first enumerated pad. + ///< Return the starting number that is going to be used for the first enumerated pad. int GetStartNumber() const; - ///> Returns common prefix for all enumerated pads. + ///< Return common prefix for all enumerated pads. wxString GetPrefix() const; }; diff --git a/pcbnew/dialogs/dialog_gencad_export_options.h b/pcbnew/dialogs/dialog_gencad_export_options.h index d686f18714..55b35a021d 100644 --- a/pcbnew/dialogs/dialog_gencad_export_options.h +++ b/pcbnew/dialogs/dialog_gencad_export_options.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2017 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -30,7 +32,7 @@ class PCB_EDIT_FRAME; class wxFilePickerCtrl; -///> Settings for GenCAD exporter +///< Settings for GenCAD exporter enum GENCAD_EXPORT_OPT { FLIP_BOTTOM_PADS, // flip bottom components padstacks geometry @@ -47,19 +49,19 @@ public: DIALOG_GENCAD_EXPORT_OPTIONS( PCB_EDIT_FRAME* aParent, const wxString& aPath ); ~DIALOG_GENCAD_EXPORT_OPTIONS(); - ///> Checks whether an option has been selected + ///< Check whether an option has been selected. bool GetOption( GENCAD_EXPORT_OPT aOption ) const; - ///> Returns all export settings + ///< Return all export settings. std::map GetAllOptions() const; - ///> Returns the selected file path + ///< Return the selected file path. wxString GetFileName() const; protected: bool TransferDataFromWindow() override; - ///> Creates checkboxes for GenCAD export options + ///< Create checkboxes for GenCAD export options. void createOptCheckboxes(); std::map m_options; diff --git a/pcbnew/dialogs/dialog_print_pcbnew.cpp b/pcbnew/dialogs/dialog_print_pcbnew.cpp index 4c837daddb..425df816d7 100644 --- a/pcbnew/dialogs/dialog_print_pcbnew.cpp +++ b/pcbnew/dialogs/dialog_print_pcbnew.cpp @@ -2,9 +2,10 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2010-2016 Jean-Pierre Charras, jean-pierre.charras at wanadoo.fr - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2018 CERN - * Author: Maciej Suminski + * + * @author Maciej Suminski * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -37,6 +38,7 @@ #include #include + class DIALOG_PRINT_PCBNEW : public DIALOG_PRINT_GENERIC { public: @@ -61,16 +63,16 @@ private: void onUseThemeChecked( wxCommandEvent& event ); void onColorModeChanged( wxCommandEvent& event ); - ///> (Un)checks all items in a checklist box + ///< (Un)check all items in a checklist box. void setListBoxValue( wxCheckListBox* aList, bool aValue ); - ///> Check whether a layer is enabled in a listbox + ///< Check whether a layer is enabled in a listbox. bool isLayerEnabled( unsigned int aLayer ) const; - ///> Enable/disable layer in a listbox + ///< Enable/disable layer in a listbox. void enableLayer( unsigned int aLayer, bool aValue ); - ///> Update layerset basing on the selected layers + ///< Update layerset basing on the selected layers. int setLayerSetFromList(); void saveSettings() override; diff --git a/pcbnew/dialogs/panel_setup_layers.h b/pcbnew/dialogs/panel_setup_layers.h index 3e222ab1ec..f8b6d59b4b 100644 --- a/pcbnew/dialogs/panel_setup_layers.h +++ b/pcbnew/dialogs/panel_setup_layers.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2018-2020 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2018-2021 KiCad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,7 +35,7 @@ class BOARD_DESIGN_SETTINGS; /** - * Holds the 3 UI control pointers for a single board layer. + * The 3 UI control pointers for a single board layer. */ struct PANEL_SETUP_LAYERS_CTLs { @@ -65,17 +65,17 @@ public: * This function warns users if they are going to delete inner copper layers because * they're importing settings from a board with less copper layers than the board * already loaded. - * @param aWorkingBoard = Currently loaded PCB - * @param aImportedBoard = PCB imported to get settings from * - * @return bool - Approval to delete inner copper if needed + * @param aWorkingBoard is the currently loaded PCB + * @param aImportedBoard is the PCB imported to get settings from. + * @return Approval to delete inner copper if needed. */ bool CheckCopperLayerCount( BOARD* aWorkingBoard, BOARD* aImportedBoard ); - ///> @return the selected layer mask within the UI checkboxes + ///< @return the selected layer mask within the UI checkboxes LSET GetUILayerMask(); - ///> @return the layer name within the UI wxTextCtrl + ///< @return the layer name within the UI wxTextCtrl wxString GetLayerName( LAYER_NUM layer ); private: diff --git a/pcbnew/files.cpp b/pcbnew/files.cpp index f169bb7013..3fe51efab5 100644 --- a/pcbnew/files.cpp +++ b/pcbnew/files.cpp @@ -3,7 +3,7 @@ * * Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2011 Wayne Stambaugh - * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -64,16 +64,13 @@ /** - * Function AskLoadBoardFileName - * puts up a wxFileDialog asking for a BOARD filename to open. + * Show a wxFileDialog asking for a #BOARD filename to open. * * @param aParent is a wxFrame passed to wxFileDialog. * @param aCtl is where to put the OpenProjectFiles() control bits. - * * @param aFileName on entry is a probable choice, on return is the chosen filename. - * @param aKicadFilesOnly true to list kiacad pcb files plugins only, false to list import plugins. - * - * @return bool - true if chosen, else false if user aborted. + * @param aKicadFilesOnly true to list KiCad pcb files plugins only, false to list import plugins. + * @return true if chosen, else false if user aborted. */ bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bool aKicadFilesOnly ) { @@ -89,15 +86,32 @@ bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bo IO_MGR::PCB_FILE_T pluginType; } loaders[] = { - { PcbFileWildcard(), IO_MGR::KICAD_SEXP }, // Current Kicad board files - { LegacyPcbFileWildcard(), IO_MGR::LEGACY }, // Old Kicad board files - { AltiumCircuitMakerPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_MAKER }, // Import Altium Circuit Maker board files - { AltiumCircuitStudioPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_STUDIO }, // Import Altium Circuit Studio board files - { AltiumDesignerPcbFileWildcard(), IO_MGR::ALTIUM_DESIGNER }, // Import Altium Designer board files - { CadstarPcbArchiveFileWildcard(), IO_MGR::CADSTAR_PCB_ARCHIVE }, // Import Cadstar PCB Archive board files - { EaglePcbFileWildcard(), IO_MGR::EAGLE }, // Import Eagle board files - { PCadPcbFileWildcard(), IO_MGR::PCAD }, // Import PCAD board files - { FabmasterPcbFileWildcard(), IO_MGR::FABMASTER }, // Import Fabmaster board files + // Current Kicad board files. + { PcbFileWildcard(), IO_MGR::KICAD_SEXP }, + + // Old Kicad board files. + { LegacyPcbFileWildcard(), IO_MGR::LEGACY }, + + // Import Altium Circuit Maker board files. + { AltiumCircuitMakerPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_MAKER }, + + // Import Altium Circuit Studio board files. + { AltiumCircuitStudioPcbFileWildcard(), IO_MGR::ALTIUM_CIRCUIT_STUDIO }, + + // Import Altium Designer board files. + { AltiumDesignerPcbFileWildcard(), IO_MGR::ALTIUM_DESIGNER }, + + // Import Cadstar PCB Archive board files. + { CadstarPcbArchiveFileWildcard(), IO_MGR::CADSTAR_PCB_ARCHIVE }, + + // Import Eagle board files. + { EaglePcbFileWildcard(), IO_MGR::EAGLE }, + + // Import PCAD board files. + { PCadPcbFileWildcard(), IO_MGR::PCAD }, + + // Import Fabmaster board files. + { FabmasterPcbFileWildcard(), IO_MGR::FABMASTER }, }; // clang-format on @@ -176,7 +190,7 @@ bool AskLoadBoardFileName( wxWindow* aParent, int* aCtl, wxString* aFileName, bo } -///> Helper widget to select whether a new project should be created for a file when saving +///< Helper widget to select whether a new project should be created for a file when saving class CREATE_PROJECT_CHECKBOX : public wxPanel { public: @@ -211,14 +225,13 @@ protected: /** - * Puts up a wxFileDialog asking for a BOARD filename to save. + * Put up a wxFileDialog asking for a BOARD filename to save. * * @param aParent is a wxFrame passed to wxFileDialog. - * @param aFileName on entry is a probable choice, on return is the - * chosen full filename (includes path). - * @param aCreateProject will be filled with the state of the Create Project? checkbox if relevant - * - * @return bool - true if chosen, else false if user aborted. + * @param aFileName on entry is a probable choice, on return is the chosen full filename + * (includes path). + * @param aCreateProject will be filled with the state of the Create Project? checkbox if relevant. + * @return true if chosen, else false if user aborted. */ bool AskSaveBoardFileName( PCB_EDIT_FRAME* aParent, wxString* aFileName, bool* aCreateProject ) { @@ -227,13 +240,8 @@ bool AskSaveBoardFileName( PCB_EDIT_FRAME* aParent, wxString* aFileName, bool* a fn.SetExt( KiCadPcbFileExtension ); - wxFileDialog dlg( aParent, - _( "Save Board File As" ), - fn.GetPath(), - fn.GetFullName(), - wildcard, - wxFD_SAVE | wxFD_OVERWRITE_PROMPT - ); + wxFileDialog dlg( aParent, _( "Save Board File As" ), fn.GetPath(), fn.GetFullName(), wildcard, + wxFD_SAVE | wxFD_OVERWRITE_PROMPT ); // Add a "Create a project" checkbox in standalone mode and one isn't loaded if( Kiface().IsSingle() && aParent->Prj().IsNullProject() ) @@ -520,8 +528,9 @@ int PCB_EDIT_FRAME::inferLegacyEdgeClearance( BOARD* aBoard ) wxMessageBox( _( "If the zones on this board are refilled the Copper Edge Clearance " "setting will be used (see Board Setup > Design Rules > Constraints).\n" "This may result in different fills from previous Kicad versions which " - "used the line thicknesses of the board boundary on the Edge Cuts layer." ), - _( "Edge Clearance Warning" ), wxOK|wxICON_WARNING, this ); + "used the line thicknesses of the board boundary on the Edge Cuts " + "layer." ), + _( "Edge Clearance Warning" ), wxOK | wxICON_WARNING, this ); } return std::max( 0, edgeWidth / 2 ); @@ -578,14 +587,15 @@ bool PCB_EDIT_FRAME::OpenProjectFiles( const std::vector& aFileSet, in if( is_new && !( aCtl & KICTL_CREATE ) ) { // notify user that fullFileName does not exist, ask if user wants to create it. - wxString ask = wxString::Format( _( "PCB \"%s\" does not exist. Do you wish to create it?" ), + wxString ask = wxString::Format( _( "PCB \"%s\" does not exist. Do you wish to " + "create it?" ), fullFileName ); if( !IsOK( this, ask ) ) return false; } // Loading a complex project and build data can be time - // consumming, so display a busy cursor + // consuming, so display a busy cursor wxBusyCursor dummy; // No save prompt (we already prompted above), and only reset to a new blank board if new @@ -811,7 +821,6 @@ bool PCB_EDIT_FRAME::SavePcbFile( const wxString& aFileName, bool addToHistory, bool aChangeProject ) { // please, keep it simple. prompting goes elsewhere. - wxFileName pcbFileName = aFileName; if( pcbFileName.GetExt() == LegacyPcbFileExtension ) @@ -981,10 +990,8 @@ bool PCB_EDIT_FRAME::SavePcbCopy( const wxString& aFileName, bool aCreateProject } catch( const IO_ERROR& ioe ) { - wxString msg = wxString::Format( _( - "Error saving board file \"%s\".\n%s" ), - pcbFileName.GetFullPath(), ioe.What() - ); + wxString msg = wxString::Format( _( "Error saving board file \"%s\".\n%s" ), + pcbFileName.GetFullPath(), ioe.What() ); DisplayError( this, msg ); return false; @@ -1051,7 +1058,7 @@ bool PCB_EDIT_FRAME::doAutoSave() return false; // If the board file path is not writable, try writing to a platform specific temp file - // path. If that path isn't writabe, give up. + // path. If that path isn't writable, give up. if( !autoSaveFileName.IsDirWritable() ) { autoSaveFileName.SetPath( wxFileName::GetTempDir() ); @@ -1144,7 +1151,6 @@ bool PCB_EDIT_FRAME::importFile( const wxString& aFileName, int aFileType ) } } - // Update footprint LIB_IDs to point to the just imported library for( FOOTPRINT* footprint : GetBoard()->Footprints() ) { diff --git a/pcbnew/footprint.h b/pcbnew/footprint.h index c0a17ba80d..6d42dd10f6 100644 --- a/pcbnew/footprint.h +++ b/pcbnew/footprint.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -59,8 +59,7 @@ enum INCLUDE_NPTH_T }; /** - * Enum FOOTPRINT_ATTR_T - * is the set of attributes allowed within a FOOTPRINT, using FOOTPRINT::SetAttributes() + * The set of attributes allowed within a FOOTPRINT, using FOOTPRINT::SetAttributes() * and FOOTPRINT::GetAttributes(). These are to be ORed together when calling * FOOTPRINT::SetAttributes() */ @@ -125,53 +124,56 @@ public: return aItem && aItem->Type() == PCB_FOOTPRINT_T; } - ///> @copydoc BOARD_ITEM_CONTAINER::Add() + ///< @copydoc BOARD_ITEM_CONTAINER::Add() void Add( BOARD_ITEM* aItem, ADD_MODE aMode = ADD_MODE::INSERT ) override; - ///> @copydoc BOARD_ITEM_CONTAINER::Remove() + ///< @copydoc BOARD_ITEM_CONTAINER::Remove() void Remove( BOARD_ITEM* aItem, REMOVE_MODE aMode = REMOVE_MODE::NORMAL ) override; /** - * Function ClearAllNets * Clear (i.e. force the ORPHANED dummy net info) the net info which * depends on a given board for all pads of the footprint. + * * This is needed when a footprint is copied between the fp editor and * the board editor for instance, because net info become fully broken */ void ClearAllNets(); /** - * Function CalculateBoundingBox - * calculates the bounding box in board coordinates. + * Calculate the bounding box in board coordinates. */ void CalculateBoundingBox(); /** - * Function GetFootprintRect() * Build and returns the boundary box of the footprint excluding any text. - * @return EDA_RECT - The rectangle containing the footprint. + * + * @return The rectangle containing the footprint. */ EDA_RECT GetFootprintRect() const; /** - * Returns the last calculated bounding box of the footprint (does not recalculate it). - * (call CalculateBoundingBox() to recalculate it) - * @return EDA_RECT - The rectangle containing the footprint + * Return the last calculated bounding box of the footprint (does not recalculate it). + * (call CalculateBoundingBox() to recalculate it). + * + * @return The rectangle containing the footprint. */ EDA_RECT GetBoundingBoxBase() const { return m_boundingBox; } /** - * Returns the bounding box containing pads when the footprint - * is on the front side, orientation 0, position 0,0. - * mainly used in Gerber place file to draw a fp outline when the coutyard - * is missing or broken - * @return EDA_RECT - The rectangle containing the pads for the normalized footprint. + * Return the bounding box containing pads when the footprint is on the front side, + * orientation 0, position 0,0. + * + * Mainly used in Gerber place file to draw a footprint outline when the courtyard + * is missing or broken. + * + * @return The rectangle containing the pads for the normalized footprint. */ EDA_RECT GetFpPadsLocalBbox() const; /** - * Returns a bounding polygon for the shapes and pads in the footprint - * This operation is slower but more accurate than calculating a bounding box + * Return a bounding polygon for the shapes and pads in the footprint. + * + * This operation is slower but more accurate than calculating a bounding box. */ SHAPE_POLY_SET GetBoundingHull() const; @@ -263,8 +265,8 @@ public: void Flip( const wxPoint& aCentre, bool aFlipLeftRight ) override; /** - * Function MoveAnchorPosition - * Move the reference point of the footprint + * Move the reference point of the footprint. + * * It looks like a move footprint: * the footprints elements (pads, outlines, edges .. ) are moved * However: @@ -276,7 +278,6 @@ public: void MoveAnchorPosition( const wxPoint& aMoveVector ); /** - * function IsFlipped * @return true if the footprint is flipped, i.e. on the back side of the board */ bool IsFlipped() const { return GetLayer() == B_Cu; } @@ -301,9 +302,9 @@ public: } /** - * Function SetLocked - * sets the MODULE_is_LOCKED bit in the m_ModuleStatus - * @param isLocked When true means turn on locked status, else unlock + * Set the #MODULE_is_LOCKED bit in the m_ModuleStatus. + * + * @param isLocked true means turn on locked status, else unlock */ void SetLocked( bool isLocked ) override { @@ -347,25 +348,25 @@ public: void SetLastEditTime() { m_lastEditTime = time( NULL ); } timestamp_t GetLastEditTime() const { return m_lastEditTime; } - /* drawing functions */ - /** - * function TransformPadsShapesWithClearanceToPolygon - * generate pads shapes on layer aLayer as polygons and adds these polygons to aCornerBuffer + * Generate pads shapes on layer \a aLayer as polygons and adds these polygons to + * \a aCornerBuffer. + * * Useful to generate a polygonal representation of a footprint in 3D view and plot functions, - * when a full polygonal approach is needed - * @param aLayer = the layer to consider, or UNDEFINED_LAYER to consider all - * @param aCornerBuffer = the buffer to store polygons - * @param aClearance = an additionnal size to add to pad shapes - * @param aMaxError = Maximum deviation from true for arcs - * @param aSkipNPTHPadsWihNoCopper = if true, do not add a NPTH pad shape, if the shape has + * when a full polygonal approach is needed. + * + * @param aLayer is the layer to consider, or #UNDEFINED_LAYER to consider all layers. + * @param aCornerBuffer i the buffer to store polygons. + * @param aClearance is an additional size to add to pad shapes. + * @param aMaxError is the maximum deviation from true for arcs. + * @param aSkipNPTHPadsWihNoCopper if true, do not add a NPTH pad shape, if the shape has * same size and position as the hole. Usually, these pads are not drawn on copper * layers, because there is actually no copper * Due to diff between layers and holes, these pads must be skipped to be sure * there is no copper left on the board (for instance when creating Gerber Files or * 3D shapes). Defaults to false. - * @param aSkipPlatedPads = used on 3D-Viewer to extract plated and nontplated pads. - * @param aSkipNonPlatedPads = used on 3D-Viewer to extract plated and plated pads. + * @param aSkipPlatedPads is used on 3D-Viewer to extract plated and non-plated pads. + * @param aSkipNonPlatedPads is used on 3D-Viewer to extract plated and plated pads. */ void TransformPadsWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, PCB_LAYER_ID aLayer, int aClearance, @@ -375,17 +376,18 @@ public: bool aSkipNonPlatedPads = false ) const; /** - * function TransformFPShapesWithClearanceToPolygon - * generate shapes of graphic items (outlines) on layer aLayer as polygons and adds these - * polygons to aCornerBuffer + * Generate shapes of graphic items (outlines) on layer \a aLayer as polygons and adds these + * polygons to \a aCornerBuffer. + * * Useful to generate a polygonal representation of a footprint in 3D view and plot functions, - * when a full polygonal approach is needed - * @param aLayer = the layer to consider, or UNDEFINED_LAYER to consider all - * @param aCornerBuffer = the buffer to store polygons - * @param aClearance = a value to inflate shapes - * @param aError = Maximum error between true arc and polygon approx - * @param aIncludeText = True to transform text shapes - * @param aIncludeShapes = True to transform footprint shapes + * when a full polygonal approach is needed. + * + * @param aLayer is the layer to consider, or #UNDEFINED_LAYER to consider all. + * @param aCornerBuffer is the buffer to store polygons. + * @param aClearance is a value to inflate shapes. + * @param aError is the maximum error between true arc and polygon approximation. + * @param aIncludeText set to true to transform text shapes. + * @param aIncludeShapes set to true to transform footprint shapes. */ void TransformFPShapesWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, PCB_LAYER_ID aLayer, int aClearance, @@ -394,9 +396,8 @@ public: bool aIncludeShapes = true ) const; /** - * @brief TransformFPTextWithClearanceToPolygonSet * This function is the same as TransformGraphicShapesWithClearanceToPolygonSet - * but only generate text + * but only generate text. */ void TransformFPTextWithClearanceToPolygonSet( SHAPE_POLY_SET& aCornerBuffer, PCB_LAYER_ID aLayer, int aClearance, @@ -413,20 +414,21 @@ public: /** * Resolve any references to system tokens supported by the component. + * * @param aDepth a counter to limit recursion and circular references. */ bool ResolveTextVar( wxString* token, int aDepth = 0 ) const; - ///> @copydoc EDA_ITEM::GetMsgPanelInfo + ///< @copydoc EDA_ITEM::GetMsgPanelInfo void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; bool HitTest( const wxPoint& aPosition, int aAccuracy = 0 ) const override; /** - * Tests if a point is inside the bounding polygon of the footprint + * Test if a point is inside the bounding polygon of the footprint. * - * The other hit test methods are just checking the bounding box, which - * can be quite inaccurate for rotated or oddly-shaped footprints. + * The other hit test methods are just checking the bounding box, which can be quite + * inaccurate for rotated or oddly-shaped footprints. * * @param aPosition is the point to test * @return true if aPosition is inside the bounding polygon @@ -436,8 +438,7 @@ public: bool HitTest( const EDA_RECT& aRect, bool aContained, int aAccuracy = 0 ) const override; /** - * Function GetReference - * @return const wxString& - the reference designator text. + * @return reference designator text. */ const wxString GetReference() const { @@ -445,7 +446,6 @@ public: } /** - * Function SetReference * @param aReference A reference to a wxString object containing the reference designator * text. */ @@ -455,14 +455,12 @@ public: } /** - * Function IncrementReference - * Bumps the current reference by aDelta. + * Bump the current reference by \a aDelta. */ void IncrementReference( int aDelta ); /** - * Function GetValue - * @return const wxString& - the value text. + * @return the value text. */ const wxString GetValue() const { @@ -470,7 +468,6 @@ public: } /** - * Function SetValue * @param aValue A reference to a wxString object containing the value text. */ void SetValue( const wxString& aValue ) @@ -490,29 +487,30 @@ public: void SetProperties( const std::map& aProps ) { m_properties = aProps; } /** - * Function FindPadByName - * returns a PAD* with a matching name. Note that names may not be - * unique, depending on how the foot print was created. - * @param aPadName the pad name to find - * @return PAD* - The first matching name is returned, or NULL if not found. + * Return a #PAD with a matching name. + * + * @note Names may not be unique depending on how the footprint was created. + * + * @param aPadName the pad name to find. + * @return the first matching named #PAD is returned or NULL if not found. */ PAD* FindPadByName( const wxString& aPadName ) const; /** - * Function GetPad - * get a pad at \a aPosition on \a aLayerMask in the footprint. + * Get a pad at \a aPosition on \a aLayerMask in the footprint. * * @param aPosition A wxPoint object containing the position to hit test. * @param aLayerMask A layer or layers to mask the hit test. - * @return A pointer to a PAD object if found otherwise NULL. + * @return A pointer to a #PAD object if found otherwise NULL. */ PAD* GetPad( const wxPoint& aPosition, LSET aLayerMask = LSET::AllLayersMask() ); PAD* GetTopLeftPad(); /** - * Gets the first pad in the list or NULL if none - * @return first pad or null pointer + * Get the first pad in the list or NULL if none. + * + * @return first pad or null pointer. */ PAD* GetFirstPad() const { @@ -520,8 +518,7 @@ public: } /** - * GetPadCount - * returns the number of pads. + * Return the number of pads. * * @param aIncludeNPTH includes non-plated through holes when true. Does not include * non-plated through holes when false. @@ -530,12 +527,10 @@ public: unsigned GetPadCount( INCLUDE_NPTH_T aIncludeNPTH = INCLUDE_NPTH_T(INCLUDE_NPTH) ) const; /** - * GetUniquePadCount - * returns the number of unique pads. - * A complex pad can be built with many pads having the same pad name - * to create a complex shape or fragmented solder paste areas. + * Return the number of unique non-blank pads. * - * GetUniquePadCount calculate the count of not blank pad names + * A complex pad can be built with many pads having the same pad name to create a complex + * shape or fragmented solder paste areas. * * @param aIncludeNPTH includes non-plated through holes when true. Does not include * non-plated through holes when false. @@ -544,8 +539,7 @@ public: unsigned GetUniquePadCount( INCLUDE_NPTH_T aIncludeNPTH = INCLUDE_NPTH_T(INCLUDE_NPTH) ) const; /** - * Function GetNextPadName - * returns the next available pad name in the footprint + * Return the next available pad name in the footprint. * * @param aFillSequenceGaps true if the numbering should "fill in" gaps in the sequence, * else return the highest value + 1 @@ -567,15 +561,14 @@ public: BOARD_ITEM* Duplicate() const override; /** - * Function DuplicateItem - * Duplicate a given item within the footprint, optionally adding it to the board - * @return the new item, or NULL if the item could not be duplicated + * Duplicate a given item within the footprint, optionally adding it to the board. + * + * @return the new item, or NULL if the item could not be duplicated. */ BOARD_ITEM* DuplicateItem( const BOARD_ITEM* aItem, bool aAddToFootprint = false ); /** - * Function Add3DModel - * adds \a a3DModel definition to the end of the 3D model list. + * Add \a a3DModel definition to the end of the 3D model list. * * @param a3DModel A pointer to a #FP_3DMODEL to add to the list. */ @@ -595,20 +588,20 @@ public: EDA_ITEM* Clone() const override; /** - * Function RunOnChildren + * Invoke a function on all BOARD_ITEMs that belong to the footprint (pads, drawings, texts). + * + * @note This function should not add or remove items to the footprint. * - * Invokes a function on all BOARD_ITEMs that belong to the footprint (pads, drawings, texts). - * Note that this function should not add or remove items to the footprint * @param aFunction is the function to be invoked. */ void RunOnChildren( const std::function& aFunction ) const; /** - * Returns a set of all layers that this footprint has drawings on similar to ViewGetLayers() + * Return a set of all layers that this footprint has drawings on similar to ViewGetLayers(). * - * @param aLayers is an array to store layer ids - * @param aCount is the number of layers stored in the array - * @param aIncludePads controls whether to also include pad layers + * @param aLayers is an array to store layer ids. + * @param aCount is the number of layers stored in the array. + * @param aIncludePads controls whether to also include pad layers. */ void GetAllDrawingLayers( int aLayers[], int& aCount, bool aIncludePads = true ) const; @@ -619,35 +612,36 @@ public: virtual const BOX2I ViewBBox() const override; /** - * static function IsLibNameValid * Test for validity of a name of a footprint to be used in a footprint library - * ( no spaces, dir separators ... ) - * @param aName = the name in library to validate + * ( no spaces, dir separators ... ). + * + * @param aName is the name in library to validate. * @return true if the given name is valid */ static bool IsLibNameValid( const wxString& aName ); /** - * static function StringLibNameInvalidChars - * Test for validity of the name in a library of the footprint - * ( no spaces, dir separators ... ) - * @param aUserReadable = false to get the list of invalid chars - * true to get a readable form (i.e ' ' = 'space' '\\t'= 'tab') - * @return a constant std::string giving the list of invalid chars in lib name + * Test for validity of the name in a library of the footprint ( no spaces, dir + * separators ... ). + * + * @param aUserReadable set to false to get the list of invalid characters or true to get + * a readable form (i.e ' ' = 'space' '\\t'= 'tab'). + * + * @return the list of invalid chars in the library name. */ static const wxChar* StringLibNameInvalidChars( bool aUserReadable ); /** - * Function SetInitialComments - * takes ownership of caller's heap allocated aInitialComments block. The comments - * are single line strings already containing the s-expression comments with optional - * leading whitespace and then a '#' character followed by optional single line text - * (text with no line endings, not even one). - * This block of single line comments will be output upfront of any generated - * s-expression text in the PCBIO::Format() function. - *

- * Note that a block of single line comments constitutes a multiline block of single - * line comments. That is, the block is made of consecutive single line comments. + * Take ownership of caller's heap allocated aInitialComments block. + * + * The comments are single line strings already containing the s-expression comments with + * optional leading whitespace and then a '#' character followed by optional single line + * text (text with no line endings, not even one). This block of single line comments + * will be output upfront of any generated s-expression text in the PCBIO::Format() function. + * + * @note A block of single line comments constitutes a multiline block of single line + * comments. That is, the block is made of consecutive single line comments. + * * @param aInitialComments is a heap allocated wxArrayString or NULL, which the caller * gives up ownership of over to this FOOTPRINT. */ @@ -658,28 +652,31 @@ public: } /** - * Function CoverageRatio - * Calculates the ratio of total area of the footprint pads and graphical items - * to the area of the footprint. Used by selection tool heuristics. - * @return the ratio + * Calculate the ratio of total area of the footprint pads and graphical items to the + * area of the footprint. Used by selection tool heuristics. + * + * @return the ratio. */ double CoverageRatio( const GENERAL_COLLECTOR& aCollector ) const; static double GetCoverageArea( const BOARD_ITEM* aItem, const GENERAL_COLLECTOR& aCollector ); - /// Return the initial comments block or NULL if none, without transfer of ownership. + ///< Return the initial comments block or NULL if none, without transfer of ownership. const wxArrayString* GetInitialComments() const { return m_initial_comments; } - /** Used in DRC to test the courtyard area (a complex polygon) - * @return the courtyard polygon + /** + * Used in DRC to test the courtyard area (a complex polygon). + * + * @return the courtyard polygon. */ SHAPE_POLY_SET& GetPolyCourtyardFront() { return m_poly_courtyard_front; } SHAPE_POLY_SET& GetPolyCourtyardBack() { return m_poly_courtyard_back; } /** - * Builds complex polygons of the courtyard areas from graphic items on the courtyard layers - * @remark sets the MALFORMED_F_COURTYARD and MALFORMED_B_COURTYARD status flags if the given - * courtyard layer does not contain a (single) closed shape + * Build complex polygons of the courtyard areas from graphic items on the courtyard layers. + * + * @note Set the #MALFORMED_F_COURTYARD and #MALFORMED_B_COURTYARD status flags if the given + * courtyard layer does not contain a (single) closed shape. */ void BuildPolyCourtyards( OUTLINE_ERROR_HANDLER* aErrorHandler = nullptr ); diff --git a/pcbnew/footprint_edit_frame.h b/pcbnew/footprint_edit_frame.h index accde2a8a6..e4b07f6857 100644 --- a/pcbnew/footprint_edit_frame.h +++ b/pcbnew/footprint_edit_frame.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -37,29 +37,16 @@ namespace PCB { struct IFACE; } // A KIFACE_I coded in pcbnew.c class FOOTPRINT_EDIT_FRAME : public PCB_BASE_EDIT_FRAME { - friend struct PCB::IFACE; - - FOOTPRINT_TREE_PANE* m_treePane; - - wxObjectDataPtr m_adapter; - - std::unique_ptr m_revertModule; - wxString m_footprintNameWhenLoaded; - - int m_defaultLibWidth; - public: - ~FOOTPRINT_EDIT_FRAME(); /** - * Function GetFootprintEditorFrameName (static) - * @return the frame name used when creating the frame - * used to get a reference to this frame, if exists + * @return the frame name used when creating the frame used to get a reference to this + * frame, if exists */ static const wxChar* GetFootprintEditorFrameName(); - ///> @copydoc PCB_BASE_FRAME::GetModel() + ///< @copydoc PCB_BASE_FRAME::GetModel() BOARD_ITEM_CONTAINER* GetModel() const override; SELECTION& GetCurrentSelection() override; @@ -96,14 +83,15 @@ public: void OnExitKiCad( wxCommandEvent& aEvent ); /** - * switches currently used canvas (Cairo / OpenGL). - * It also reinit the layers manager that slightly changes with canvases + * Switch the currently used canvas (Cairo / OpenGL). + * + * It also reinitializes the layer manager that slightly changes with canvases. */ void SwitchCanvas( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ) override; /** - * Update the layer manager and other widgets from the board setup - * (layer and items visibility, colors ...) + * Update the layer manager and other widgets from the board setup (layer and items + * visibility, colors ...). */ void UpdateUserInterface(); @@ -126,11 +114,12 @@ public: void ReCreateMenuBar() override; /** - * Re create the layer Box by clearing the old list, and building - * le new one, from the new layers names and cole layers - * @param aForceResizeToolbar = true to resize the parent toolbar - * false if not needed (mainly in parent toolbar creation, - * or when the layers names are not modified) + * Re create the layer Box by clearing the old list, and building a new one from the new + * layers names and layer colors.. + * + * @param aForceResizeToolbar true to resize the parent toolbar or false if not needed + * (mainly in parent toolbar creation or when the layers names + * are not modified). */ void ReCreateLayerBox( bool aForceResizeToolbar = true ); @@ -138,7 +127,7 @@ public: void SelectLayer( wxCommandEvent& event ); - // The Tool Framework initalization, for GAL mode + // The Tool Framework initialization, for GAL mode void setupTools(); void OnSaveFootprintAsPng( wxCommandEvent& event ); @@ -149,8 +138,9 @@ public: /** * Save a library to a new name and/or library type. * + * @see #PLUGIN::FootprintSave and #PLUGIN::FootprintLibCreate + * * @note Saving as a new library type requires the plug-in to support saving libraries - * @see PLUGIN::FootprintSave and PLUGIN::FootprintLibCreate */ bool SaveLibraryAs( const wxString& aLibraryPath ); @@ -158,7 +148,7 @@ public: void OnUpdateLoadFootprintFromBoard( wxUpdateUIEvent& aEvent ); void OnUpdateSaveFootprintToBoard( wxUpdateUIEvent& aEvent ); - ///> @copydoc PCB_BASE_EDIT_FRAME::OnEditItemRequest() + ///< @copydoc PCB_BASE_EDIT_FRAME::OnEditItemRequest() void OnEditItemRequest( BOARD_ITEM* aItem ) override; /** @@ -171,7 +161,7 @@ public: void LoadFootprintFromLibrary( LIB_ID aFPID ); /** - * Returns the adapter object that provides the stored data. + * Return the adapter object that provides the stored data. */ wxObjectDataPtr& GetLibTreeAdapter() { return m_adapter; } @@ -188,15 +178,13 @@ public: bool RevertFootprint(); /** - * Must be called after a footprint change - * in order to set the "modify" flag of the current screen - * and prepare, if needed the refresh of the 3D frame showing the footprint - * do not forget to call the basic OnModify function to update auxiliary info + * Must be called after a footprint change in order to set the "modify" flag of the + * current screen and prepare, if needed the refresh of the 3D frame showing the footprint. + * + * Do not forget to call the basic OnModify function to update auxiliary info. */ void OnModify() override; - // BOARD handling - /** * Delete all and reinitialize the current board. * @@ -218,7 +206,6 @@ public: void ClearModify(); - // importing / exporting Footprint /** * Create a file containing only one footprint. */ @@ -230,7 +217,7 @@ public: * The import function can also read gpcb footprint file, in Newlib format. * (One footprint per file, Newlib files have no special ext.) */ - FOOTPRINT* ImportFootprint( const wxString& aName = wxT( "") ); + FOOTPRINT* ImportFootprint( const wxString& aName = wxT( "" ) ); /** * Load a footprint from the main board into the Footprint Editor. @@ -258,25 +245,25 @@ public: */ COLOR4D GetGridColor() override; - ///> @copydoc PCB_BASE_FRAME::SetActiveLayer() + ///< @copydoc PCB_BASE_FRAME::SetActiveLayer() void SetActiveLayer( PCB_LAYER_ID aLayer ) override; - ///> @copydoc PCB_BASE_FRAME::OnUpdateLayerAlpha() + ///< @copydoc PCB_BASE_FRAME::OnUpdateLayerAlpha() void OnUpdateLayerAlpha( wxUpdateUIEvent& aEvent ) override; void OnDisplayOptionsChanged() override; - ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas() + ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas() void ActivateGalCanvas() override; /** * Load a KiCad board (.kicad_pcb) from \a aFileName. * - * @param aFileSet - hold the BOARD file to load, a vector of one element. - * @param aCtl - KICTL_ bits, one to indicate that an append of the board file - * aFileName to the currently loaded file is desired. - * @see #KIWAY_PLAYER for bit defines. - * @return bool - false if file load fails, otherwise true. + * @param aFileSet is the BOARD file to load, a vector of one element. + * @param aCtl is the KICTL_ bits, one to indicate that an append of the board file + * \a aFileName to the currently loaded file is desired. @see #KIWAY_PLAYER + * for bit defines. + * @return false if file load fails, otherwise true. */ bool OpenProjectFiles( const std::vector& aFileSet, int aCtl = 0 ) override; @@ -287,7 +274,7 @@ public: void AddFootprintToBoard( FOOTPRINT* aFootprint ) override; /** - * Allows Footprint Editor to install its preferences panel into the preferences dialog. + * Allow footprint editor to install its preferences panel into the preferences dialog. */ void InstallPreferences( PAGED_DIALOG* aParent, PANEL_HOTKEYS_EDITOR* aHotkeysPanel ) override; @@ -304,7 +291,6 @@ public: /** * Synchronize the footprint library tree to the current state of the footprint library * table. - * @param aProgress */ void SyncLibraryTree( bool aProgress ); @@ -316,7 +302,7 @@ public: void RefreshLibraryTree(); - /// Reloads displayed items and sets view. + ///< Reload displayed items and sets view. void UpdateView(); void FocusOnLibID( const LIB_ID& aLibID ); @@ -353,6 +339,19 @@ protected: void editFootprintProperties( FOOTPRINT* aFootprint ); void setupUIConditions() override; + +private: + friend struct PCB::IFACE; + + FOOTPRINT_TREE_PANE* m_treePane; + + wxObjectDataPtr m_adapter; + + std::unique_ptr m_revertModule; + wxString m_footprintNameWhenLoaded; + + int m_defaultLibWidth; + }; #endif // FOOTPRINT_EDIT_FRAME_H diff --git a/pcbnew/footprint_viewer_frame.h b/pcbnew/footprint_viewer_frame.h index aa825ee204..33751fe0a1 100644 --- a/pcbnew/footprint_viewer_frame.h +++ b/pcbnew/footprint_viewer_frame.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2018 Jean-Pierre Charras, jap.charras at wanadoo.fr - * Copyright (C) 2004-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2004-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -43,20 +43,10 @@ namespace PCB { struct IFACE; } */ class FOOTPRINT_VIEWER_FRAME : public PCB_BASE_FRAME { - friend struct PCB::IFACE; // constructor called from here only - -protected: - FOOTPRINT_VIEWER_FRAME( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType ); - - MAGNETIC_SETTINGS m_magneticItems; - - void setupUIConditions() override; - - public: ~FOOTPRINT_VIEWER_FRAME(); - ///> @copydoc PCB_BASE_FRAME::GetModel() + ///< @copydoc PCB_BASE_FRAME::GetModel() BOARD_ITEM_CONTAINER* GetModel() const override; SELECTION& GetCurrentSelection() override; @@ -72,22 +62,20 @@ public: } /** - * Function ReCreateLibraryList + * Create or recreate the list of current loaded libraries. * - * Creates or recreates the list of current loaded libraries. * This list is sorted, with the library cache always at end of the list */ void ReCreateLibraryList(); /** - * Update the ID_ADD_FOOTPRINT_TO_BOARD tool state in main toolbar + * Update the ID_ADD_FOOTPRINT_TO_BOARD tool state in main toolbar. */ void OnUpdateFootprintButton( wxUpdateUIEvent& aEvent ); /** - * Function ShowModal + * Run the footprint viewer as a modal dialog. * - * Runs the Footprint Viewer as a modal dialog. * @param aFootprint an optional FPID string to initialize the viewer with and to * return a selected footprint through. */ @@ -95,15 +83,14 @@ public: COLOR_SETTINGS* GetColorSettings() const override; +protected: + FOOTPRINT_VIEWER_FRAME( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType ); + + MAGNETIC_SETTINGS m_magneticItems; + + void setupUIConditions() override; + private: - wxTextCtrl* m_libFilter; - wxListBox* m_libList; // The list of libs names - wxTextCtrl* m_fpFilter; - wxListBox* m_fpList; // The list of footprint names - - bool m_autoZoom; - double m_lastZoom; - const wxString getCurNickname(); void setCurNickname( const wxString& aNickname ); @@ -116,8 +103,7 @@ private: void OnIterateFootprintList( wxCommandEvent& event ); /** - * Function UpdateTitle - * updates the window title with current library information. + * Update the window title with current library information. */ void UpdateTitle(); @@ -148,45 +134,51 @@ private: void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged ) override; /** - * Function OnActivate - * is called when the frame frame is activate to reload the libraries and component lists + * Called when the frame frame is activate to reload the libraries and component lists * that can be changed by the schematic editor or the library editor. */ void OnActivate( wxActivateEvent& event ); /** - * Function AddFootprintToPCB - * exports the current footprint name and close the library browser. + * Export the current footprint name and close the library browser. */ void AddFootprintToPCB( wxCommandEvent& aEvent ); /** - * Function SelectAndViewFootprint - * Select and load the next or the previous footprint - * if no current footprint, Rebuild the list of footprints available in a given footprint - * library - * @param aMode = NEXT_PART or PREVIOUS_PART + * Select and load the next or the previous footprint. + * + * If no current footprint, rebuild the list of footprints available in a given footprint + * library. + * + * @param aMode #NEXT_PART or #PREVIOUS_PART. */ void SelectAndViewFootprint( int aMode ); /** - * Function Update3DView - * must be called after a footprint selection * Updates the 3D view and 3D frame title. - * @param aForceReload = true to reload data immediately + * + * Must be called after a footprint selection. + * + * @param aForceReload true to reload data immediately. */ void Update3DView( bool aForceReload, const wxString* aTitle = nullptr ) override; - /* - * Virtual functions, not used here, but needed by PCB_BASE_FRAME - * (virtual pure functions ) - */ void SaveCopyInUndoList( EDA_ITEM*, UNDO_REDO, const wxPoint& ) override {} void SaveCopyInUndoList( const PICKED_ITEMS_LIST&, UNDO_REDO, const wxPoint &) override {} void updateView(); DECLARE_EVENT_TABLE() + + friend struct PCB::IFACE; // constructor called from here only + + wxTextCtrl* m_libFilter; + wxListBox* m_libList; // The list of library names. + wxTextCtrl* m_fpFilter; + wxListBox* m_fpList; // The list of footprint names. + + bool m_autoZoom; + double m_lastZoom; }; #endif // FOOTPRINT_VIEWER_FRAME_H diff --git a/pcbnew/footprint_wizard_frame.h b/pcbnew/footprint_wizard_frame.h index 8a0148d3d1..1596522578 100644 --- a/pcbnew/footprint_wizard_frame.h +++ b/pcbnew/footprint_wizard_frame.h @@ -3,7 +3,7 @@ * * Copyright (C) 2012 Miguel Angel Ajo Pelayo, miguelangel@nbee.es * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 2004-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2004-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -58,8 +58,8 @@ private: wxListBox* m_pageList; ///< The list of pages WX_GRID* m_parameterGrid; ///< The list of parameters int m_parameterGridPage; ///< the page currently displayed by m_parameterGrid - ///< it is most of time the m_pageList selection, but can differ - ///< during transitions between pages. + ///< it is most of time the m_pageList selection, but + ///< can differ during transitions between pages. wxTextCtrl* m_buildMessageBox; wxString m_auiPerspective; ///< Encoded string describing the AUI layout @@ -77,7 +77,7 @@ public: ~FOOTPRINT_WIZARD_FRAME(); - ///> @copydoc PCB_BASE_FRAME::GetModel() + ///< @copydoc PCB_BASE_FRAME::GetModel() BOARD_ITEM_CONTAINER* GetModel() const override; FOOTPRINT* GetBuiltFootprint(); @@ -97,129 +97,115 @@ private: void OnGridSize( wxSizeEvent& aSizeEvent ); /** - * redraws the message panel. - * display the current footprint info, or - * clear the message panel if nothing is loaded + * Redraw the message panel. + * + * Display the current footprint info, or clear the message panel if nothing is loaded. */ void UpdateMsgPanel() override; /** - * rebuild the GAL view (reint tool manager, colors and drawings) - * must be run after any footprint change. + * Rebuild the GAL view (reint tool manager, colors and drawings) must be run after any + * footprint change. */ void updateView(); /** - * Function ExportSelectedFootprint(); - * will let the caller exit from the wait loop, and get the built footprint + * Will let the caller exit from the wait loop, and get the built footprint. * */ - void ExportSelectedFootprint( wxCommandEvent& aEvent ); + void ExportSelectedFootprint( wxCommandEvent& aEvent ); /** - * Function OnSashDrag - * resizes the child windows when dragging a sash window border. + * Resize the child windows when dragging a sash window border. */ - - void OnSashDrag( wxSashEvent& event ); + void OnSashDrag( wxSashEvent& event ); /** - * Function ReCreatePageList - * Creates or recreates the list of parameter pages for the current wizard. + * Create or recreate the list of parameter pages for the current wizard. + * * This list is sorted */ - void ReCreatePageList(); + void ReCreatePageList(); /** - * Function ReCreateParameterList - * Creates the list of parameters for the current page + * Create the list of parameters for the current page. */ - void ReCreateParameterList(); + void ReCreateParameterList(); /** - * Expand the 'Value' column to fill available + * Expand the 'Value' column to fill available. */ - void ResizeParamColumns(); + void ResizeParamColumns(); /** - * Function initParameterGrid - * Prepare the grid where parameters are displayed + * Prepare the grid where parameters are displayed. */ - void initParameterGrid(); + void initParameterGrid(); /** - * Function SelectFootprintWizard - * Shows the list of footprint wizards available into the system + * Show the list of footprint wizards available into the system. */ - void SelectFootprintWizard(); + void SelectFootprintWizard(); /** - * Function ReloadFootprint - * Reloads the current footprint + * Reload the current footprint. */ - void ReloadFootprint(); + void ReloadFootprint(); /** - * Function DisplayBuildMessages - * Display the message generated by the python build footprint script + * Display the message generated by the python build footprint script. */ - void DisplayBuildMessage( wxString& aMessage ); + void DisplayBuildMessage( wxString& aMessage ); /** - * Function GetMyWizard - * Reloads the wizard by name + * Reloads the wizard by name. */ - FOOTPRINT_WIZARD* GetMyWizard(); + FOOTPRINT_WIZARD* GetMyWizard(); - - void Process_Special_Functions( wxCommandEvent& event ); + void Process_Special_Functions( wxCommandEvent& event ); /** - * Function DisplayWizardInfos - * Shows all the details about the current wizard + * Show all the details about the current wizard. */ - void DisplayWizardInfos(); + void DisplayWizardInfos(); + void doCloseWindow() override; + void ReCreateHToolbar() override; + void ReCreateVToolbar() override; + void ClickOnPageList( wxCommandEvent& event ); - void doCloseWindow() override; - void ReCreateHToolbar() override; - void ReCreateVToolbar() override; - void ClickOnPageList( wxCommandEvent& event ); + void LoadSettings( APP_SETTINGS_BASE* aCfg ) override; + void SaveSettings( APP_SETTINGS_BASE* aCfg ) override; - void LoadSettings( APP_SETTINGS_BASE* aCfg ) override; - void SaveSettings( APP_SETTINGS_BASE* aCfg ) override; - - WINDOW_SETTINGS* GetWindowSettings( APP_SETTINGS_BASE* aCfg ) override; - - /** - * Function OnActivate - * is called when the frame frame is activate to reload the libraries and component lists - * that can be changed by the schematic editor or the library editor. - */ - void OnActivate( wxActivateEvent& event ); - - void SelectCurrentWizard( wxCommandEvent& event ); - - void DefaultParameters( wxCommandEvent& event ); + WINDOW_SETTINGS* GetWindowSettings( APP_SETTINGS_BASE* aCfg ) override; /** - * Function ParametersUpdated - * Update the footprint python parameters values from the values in grid + * Called when the frame frame is activate to reload the libraries and component lists + * that can be changed by the schematic editor or the library editor. */ - void ParametersUpdated( wxGridEvent& event ); + void OnActivate( wxActivateEvent& event ); + + void SelectCurrentWizard( wxCommandEvent& event ); + + void DefaultParameters( wxCommandEvent& event ); /** - * Function Update3D_Frame - * must be called after a footprint selection + * Update the footprint python parameters values from the values in grid. + */ + void ParametersUpdated( wxGridEvent& event ); + + /** + * Must be called after a footprint selection. + * * Updates the 3D view and 3D frame title. - * @param aForceReload = true to reload data immediately - * @param aTitle (optional) the window title to set for the viewer + * + * @param aForceReload true to reload data immediately. + * @param aTitle (optional) the window title to set for the viewer. */ - void Update3DView( bool aForceReload, const wxString* aTitle ) override; + void Update3DView( bool aForceReload, const wxString* aTitle ) override; /* - * Virtual functions, not used here, but needed by PCB_BASE_EDIT_FRAME - * (virtual pure functions ) + * Not used here but needed by PCB_BASE_EDIT_FRAME. */ void SaveCopyInUndoList( EDA_ITEM*, UNDO_REDO, const wxPoint& ) override {} void SaveCopyInUndoList( const PICKED_ITEMS_LIST&, UNDO_REDO, const wxPoint& ) override {} diff --git a/pcbnew/fp_text.h b/pcbnew/fp_text.h index 4a611cbf46..55c0b40e9f 100644 --- a/pcbnew/fp_text.h +++ b/pcbnew/fp_text.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2004 Jean-Pierre Charras, jaen-pierre.charras@gipsa-lab.inpg.com - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -102,8 +102,8 @@ public: void KeepUpright( double aOldOrientation, double aNewOrientation ); /** - * @return force the text rotation to be always between -90 .. 90 deg. Otherwise the text is not easy to read - * if false, the text rotation is free. + * @return force the text rotation to be always between -90 .. 90 deg. Otherwise the text + * is not easy to read if false, the text rotation is free. */ bool IsKeepUpright() const { @@ -139,8 +139,7 @@ public: TEXT_TYPE GetType() const { return m_Type; } /** - * Function SetEffects - * sets the text effects from another instance. + * Set the text effects from another instance. */ void SetEffects( const FP_TEXT& aSrc ) { @@ -150,8 +149,7 @@ public: } /** - * Function SwapEffects - * swaps the text effects of the two involved instances. + * Swap the text effects of the two involved instances. */ void SwapEffects( FP_TEXT& aTradingPartner ) { @@ -161,15 +159,15 @@ public: // std::swap( m_Type, aTradingPartner.m_Type ); } - // The Pos0 accessors are for footprint-relative coordinates + // The Pos0 accessors are for footprint-relative coordinates. void SetPos0( const wxPoint& aPos ) { m_Pos0 = aPos; SetDrawCoord(); } const wxPoint& GetPos0() const { return m_Pos0; } int GetLength() const; // text length /** - * @return the text rotation for drawings and plotting - * the footprint rotation is taken in account + * @return the text rotation for drawings and plotting the footprint rotation is taken + * in account. */ virtual double GetDrawRotation() const override; double GetDrawRotationRadians() const { return GetDrawRotation() * M_PI/1800; } @@ -177,10 +175,10 @@ public: // Virtual function const EDA_RECT GetBoundingBox() const override; - ///> Set absolute coordinates. + ///< Set absolute coordinates. void SetDrawCoord(); - ///> Set relative coordinates. + ///< Set relative coordinates. void SetLocalCoord(); void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; diff --git a/pcbnew/import_gfx/graphics_import_mgr.h b/pcbnew/import_gfx/graphics_import_mgr.h index 4100fb9d4f..10fff3799c 100644 --- a/pcbnew/import_gfx/graphics_import_mgr.h +++ b/pcbnew/import_gfx/graphics_import_mgr.h @@ -2,8 +2,9 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016 CERN + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,12 +34,12 @@ class GRAPHICS_IMPORT_PLUGIN; class wxString; /** - * @brief Class to manage vector graphics importers. + * Manage vector graphics importers. */ class GRAPHICS_IMPORT_MGR { public: - ///> List of handled file types. + ///< List of handled file types. enum GFX_FILE_T { DXF, @@ -54,16 +55,16 @@ public: */ GRAPHICS_IMPORT_MGR( const TYPE_LIST& aBlacklist ); - ///> Vector containing all GFX_FILE_T values that can be imported. + ///< Vector containing all GFX_FILE_T values that can be imported. TYPE_LIST GetImportableFileTypes() const { return m_importableTypes; } - ///> Returns a plugin that handles a specific file extension. + ///< Returns a plugin that handles a specific file extension. std::unique_ptr GetPluginByExt( const wxString& aExtension ) const; - ///> Returns a plugin instance for a specific file type. + ///< Returns a plugin instance for a specific file type. std::unique_ptr GetPlugin( GFX_FILE_T aType ) const; private: diff --git a/pcbnew/import_gfx/graphics_import_plugin.h b/pcbnew/import_gfx/graphics_import_plugin.h index 2ef00c5eeb..42e8d0010d 100644 --- a/pcbnew/import_gfx/graphics_import_plugin.h +++ b/pcbnew/import_gfx/graphics_import_plugin.h @@ -2,7 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -121,7 +122,7 @@ public: const virtual std::string& GetMessages() const = 0; protected: - ///> Importer used to create objects representing the imported shapes. + ///< Importer used to create objects representing the imported shapes. GRAPHICS_IMPORTER* m_importer; }; diff --git a/pcbnew/import_gfx/graphics_importer.h b/pcbnew/import_gfx/graphics_importer.h index 5fe53041c1..8545beff94 100644 --- a/pcbnew/import_gfx/graphics_importer.h +++ b/pcbnew/import_gfx/graphics_importer.h @@ -2,7 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -109,7 +110,7 @@ public: } /** - * Sets the line width for the imported outlines (in mm). + * Set the line width for the imported outlines (in mm). */ void SetLineWidthMM( double aWidth ) { @@ -117,7 +118,7 @@ public: } /** - * Returns the line width used for importing the outlines (in mm). + * Return the line width used for importing the outlines (in mm). */ double GetLineWidthMM() const { @@ -133,8 +134,7 @@ public: } /** - * @return the offset to add to coordinates when importing graphic items. - * The offset is always in mm + * @return the offset in millimeters to add to coordinates when importing graphic items. */ const VECTOR2D& GetImportOffsetMM() const { @@ -142,8 +142,7 @@ public: } /** - * Set the offset to add to coordinates when importing graphic items. - * The offset is always in mm + * Set the offset in millimeters to add to coordinates when importing graphic items. */ void SetImportOffsetMM( const VECTOR2D& aOffset ) { @@ -152,7 +151,8 @@ public: /** * Set the scale factor affecting the imported shapes. - * it allows conversion between imported shapes units and mm + * + * This allows conversion between imported shapes units and millimeters. */ void SetScale( double aScale ) { @@ -183,11 +183,9 @@ public: return m_items; } - ///> Default line thickness (in mm) + ///< Default line thickness (in mm) static constexpr unsigned int DEFAULT_LINE_WIDTH_DFX = 1; - // Methods to be implemented by derived graphics importers - /** * Create an object representing a line segment. * @@ -204,7 +202,8 @@ public: * @param aRadius is the circle radius expressed in mm. * @param aWidth is the segment thickness in mm. Use -1 for default line thickness */ - virtual void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth, bool aFilled ) = 0; + virtual void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth, + bool aFilled ) = 0; /** * Create an object representing an arc. @@ -250,23 +249,23 @@ public: double aWidth ) = 0; protected: - ///> Adds an item to the imported shapes list. + ///< Add an item to the imported shapes list. void addItem( std::unique_ptr aItem ) { m_items.emplace_back( std::move( aItem ) ); } private: - ///> List of imported items + ///< List of imported items std::list> m_items; - ///> Plugin used to load a file + ///< Plugin used to load a file std::unique_ptr m_plugin; - ///> Total image width + ///< Total image width double m_originalWidth; - ///> Total image Height; + ///< Total image Height; double m_originalHeight; /** @@ -276,14 +275,14 @@ private: */ double m_scale; - ///> Default line thickness for the imported graphics + ///< Default line thickness for the imported graphics double m_lineWidth; protected: - ///> factor to convert millimeters to Internal Units + ///< factor to convert millimeters to Internal Units double m_millimeterToIu; - ///> Offset (in mm) for imported coordinates + ///< Offset (in mm) for imported coordinates VECTOR2D m_offsetCoordmm; }; diff --git a/pcbnew/import_gfx/graphics_importer_buffer.h b/pcbnew/import_gfx/graphics_importer_buffer.h index 29cf1f4877..c539037976 100644 --- a/pcbnew/import_gfx/graphics_importer_buffer.h +++ b/pcbnew/import_gfx/graphics_importer_buffer.h @@ -2,8 +2,9 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2017 CERN + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Janito Vaqueiro Ferreira Filho - * Copyright (C) 2018-2019 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -323,13 +324,14 @@ public: void AddCircle( const VECTOR2D& aCenter, double aRadius, double aWidth, bool aFilled ) override; - void AddArc( const VECTOR2D& aCenter, const VECTOR2D& aStart, double aAngle, double aWidth ) override; + void AddArc( const VECTOR2D& aCenter, const VECTOR2D& aStart, double aAngle, + double aWidth ) override; void AddPolygon( const std::vector< VECTOR2D >& aVertices, double aWidth ) override; void AddText( const VECTOR2D& aOrigin, const wxString& aText, - double aHeight, double aWidth, double aThickness, double aOrientation, - EDA_TEXT_HJUSTIFY_T aHJustify, EDA_TEXT_VJUSTIFY_T aVJustify ) override; + double aHeight, double aWidth, double aThickness, double aOrientation, + EDA_TEXT_HJUSTIFY_T aHJustify, EDA_TEXT_VJUSTIFY_T aVJustify ) override; void AddSpline( const VECTOR2D& aStart, const VECTOR2D& BezierControl1, const VECTOR2D& BezierControl2, const VECTOR2D& aEnd , double aWidth ) override; @@ -343,7 +345,7 @@ public: } protected: - ///> List of imported shapes + ///< List of imported shapes std::list< std::unique_ptr< IMPORTED_SHAPE > > m_shapes; }; diff --git a/pcbnew/import_gfx/graphics_importer_pcbnew.h b/pcbnew/import_gfx/graphics_importer_pcbnew.h index d7cc20835a..958bd7204e 100644 --- a/pcbnew/import_gfx/graphics_importer_pcbnew.h +++ b/pcbnew/import_gfx/graphics_importer_pcbnew.h @@ -2,8 +2,9 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016 CERN + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski - * Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -42,7 +43,8 @@ public: GRAPHICS_IMPORTER_PCBNEW(); /** - * @brief Sets the target layer for the imported shapes. + * Set the target layer for the imported shapes. + * * @param aLayer is the layer to be used by the imported shapes. */ void SetLayer( PCB_LAYER_ID aLayer ) @@ -51,7 +53,7 @@ public: } /** - * @brief Returns the target layer for the imported shapes. + * Return the target layer for the imported shapes. */ PCB_LAYER_ID GetLayer() const { @@ -72,30 +74,34 @@ public: EDA_TEXT_HJUSTIFY_T aHJustify, EDA_TEXT_VJUSTIFY_T aVJustify ) override; void AddSpline( const VECTOR2D& aStart, const VECTOR2D& aBezierControl1, - const VECTOR2D& aBezierControl2, const VECTOR2D& aEnd , double aWidth ) override; + const VECTOR2D& aBezierControl2, const VECTOR2D& aEnd, + double aWidth ) override; - /** convert a imported coordinate to a board coordinate, according to - * the internal units, the user scale and offset - * @param aCoordinate is the imported coordinate in mm + /** + * Convert an imported coordinate to a board coordinate, according to the internal units, + * user scale and offset + * + * @param aCoordinate is the imported coordinate in mm. */ wxPoint MapCoordinate( const VECTOR2D& aCoordinate ); - /** @return a line thickness in a board Iu value, according to - * the internal units. - * if aLineWidth < 0, the default ine thickness value is returned - * @param aLineWidth is the line thickness in mm to convert + /** + * If aLineWidth < 0, the default line thickness value is returned. + * + * @param aLineWidth is the line thickness in mm to convert. + * @return a line thickness in a board Iu value, according to the internal units. */ int MapLineWidth( double aLineWidth ); protected: - ///> Create an object representing a graphical shape. + ///< Create an object representing a graphical shape. virtual std::unique_ptr createDrawing() = 0; - ///> Create an object representing a text. Both pointers point to different parts of the - ///> same object, the EDA_TEXT pointer is simply for convenience. + ///< Create an object representing a text. Both pointers point to different parts of the + ///< same object, the EDA_TEXT pointer is simply for convenience. virtual std::pair, EDA_TEXT*> createText() = 0; - ///> Target layer for the imported shapes. + ///< Target layer for the imported shapes. PCB_LAYER_ID m_layer; }; diff --git a/pcbnew/microwave/microwave_tool.cpp b/pcbnew/microwave/microwave_tool.cpp index f219dcf0fc..28cd1e0eb7 100644 --- a/pcbnew/microwave/microwave_tool.cpp +++ b/pcbnew/microwave/microwave_tool.cpp @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017-2020 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -101,8 +101,8 @@ static const COLOR4D inductorAreaFill( 0.3, 0.3, 0.5, 0.3 ); static const COLOR4D inductorAreaStroke( 0.4, 1.0, 1.0, 1.0 ); static const double inductorAreaStrokeWidth = 1.0; -///> Aspect of the preview rectangle - this is hardcoded in the -///> microwave backend for now +///< Aspect of the preview rectangle - this is hardcoded in the +///< microwave backend for now static const double inductorAreaAspect = 0.5; @@ -134,9 +134,9 @@ int MICROWAVE_TOOL::drawMicrowaveInductor( const TOOL_EVENT& aEvent ) view.Add( &previewRect ); - auto setCursor = - [&]() - { + auto setCursor = + [&]() + { frame.GetCanvas()->SetCurrentCursor( KICURSOR::PENCIL ); }; @@ -245,7 +245,8 @@ void MICROWAVE_TOOL::setTransitions() Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateGap.MakeEvent() ); Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateStub.MakeEvent() ); Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateStubArc.MakeEvent() ); - Go( &MICROWAVE_TOOL::addMicrowaveFootprint, PCB_ACTIONS::microwaveCreateFunctionShape.MakeEvent() ); + Go( &MICROWAVE_TOOL::addMicrowaveFootprint, + PCB_ACTIONS::microwaveCreateFunctionShape.MakeEvent() ); Go( &MICROWAVE_TOOL::drawMicrowaveInductor, PCB_ACTIONS::microwaveCreateLine.MakeEvent() ); } diff --git a/pcbnew/microwave/microwave_tool.h b/pcbnew/microwave/microwave_tool.h index d8df47c812..221f588bca 100644 --- a/pcbnew/microwave/microwave_tool.h +++ b/pcbnew/microwave/microwave_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -51,8 +51,6 @@ public: /** - * MICROWAVE_TOOL - * * Tool responsible for adding microwave features to PCBs */ class MICROWAVE_TOOL : public PCB_TOOL_BASE @@ -61,39 +59,41 @@ public: MICROWAVE_TOOL(); ~MICROWAVE_TOOL(); - ///> React to model/view changes + ///< React to model/view changes void Reset( RESET_REASON aReason ) override; - ///> Bind handlers to corresponding TOOL_ACTIONs + ///< Bind handlers to corresponding TOOL_ACTIONs void setTransitions() override; private: - ///> Main interactive tool + ///< Main interactive tool int addMicrowaveFootprint( const TOOL_EVENT& aEvent ); - ///> Create an inductor between the two points + ///< Create an inductor between the two points void createInductorBetween( const VECTOR2I& aStart, const VECTOR2I& aEnd ); - ///> Draw a microwave inductor interactively + ///< Draw a microwave inductor interactively int drawMicrowaveInductor( const TOOL_EVENT& aEvent ); /** - * Creates a footprint "GAP" or "STUB" used in micro wave designs. - * This footprint has 2 pads: - * PAD_ATTRIB_SMD, rectangular, H size = V size = current track width. - * the "gap" is isolation created between this 2 pads + * Create a footprint "GAP" or "STUB" used in micro wave designs. * - * @param aComponentShape is the component to create - * @return the new footprint + * This footprint has 2 pads: + * PAD_ATTRIB_SMD, rectangular, H size = V size = current track width. + * the "gap" is isolation created between this 2 pads + * + * @param aComponentShape is the component to create. + * @return the new footprint. */ FOOTPRINT* createFootprint( MICROWAVE_FOOTPRINT_SHAPE aFootprintShape ); FOOTPRINT* createPolygonShape(); /** - * Creates an S-shaped coil footprint for microwave applications. + * Create an S-shaped coil footprint for microwave applications. */ - FOOTPRINT* createMicrowaveInductor( MICROWAVE_INDUCTOR_PATTERN& aPattern, wxString& aErrorMessage ); + FOOTPRINT* createMicrowaveInductor( MICROWAVE_INDUCTOR_PATTERN& aPattern, + wxString& aErrorMessage ); /** * Create a basic footprint for micro wave applications. @@ -101,10 +101,10 @@ private: * The default pad settings are: * PAD_ATTRIB_SMD, rectangular, H size = V size = current track width. * - * @param aValue is the text value - * @param aTextSize is the size of ref and value texts ( <= 0 to use board default values ) - * @param aPadCount is number of pads - * @return the new footprint + * @param aValue is the text value. + * @param aTextSize is the size of ref and value texts ( <= 0 to use board default values ). + * @param aPadCount is number of pads. + * @return the new footprint. */ FOOTPRINT* createBaseFootprint( const wxString& aValue, int aTextSize, int aPadCount ); }; diff --git a/pcbnew/netinfo.h b/pcbnew/netinfo.h index fdd1a32a76..ce749df6b4 100644 --- a/pcbnew/netinfo.h +++ b/pcbnew/netinfo.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2009 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -59,26 +59,10 @@ class PCB_BASE_FRAME; DECL_VEC_FOR_SWIG( PADS_VEC, PAD* ) /** - * NETINFO_ITEM - * handles the data for a net + * Handle the data for a net. */ class NETINFO_ITEM : public BOARD_ITEM { - friend class NETINFO_LIST; - -private: - int m_netCode; ///< A number equivalent to the net name. - wxString m_netname; ///< Full net name like /sheet/subsheet/vout used by Eeschema. - wxString m_shortNetname; ///< short net name, like vout from /sheet/subsheet/vout. - - NETCLASSPTR m_netClass; - - bool m_isCurrent; ///< Indicates the net is currently in use. We still store - ///< those that are not during a session for undo/redo and to - ///< keep netclass membership information. - - BOARD* m_parent; ///< The parent board the net belongs to. - public: NETINFO_ITEM( BOARD* aParent, const wxString& aNetName = wxEmptyString, int aNetCode = -1 ); @@ -113,10 +97,8 @@ public: void SetNetClass( const NETCLASSPTR& aNetClass ); /** - * Function GetNetClass - * - * Note: do NOT return a std::shared_ptr from this. It is used heavily in DRC, and the - * std::shared_ptr stuff shows up large in performance profiling. + * @note Do **not** return a std::shared_ptr from this. It is used heavily in DRC, and the + * std::shared_ptr stuff shows up large in performance profiling. */ NETCLASS* GetNetClass() { @@ -132,20 +114,17 @@ public: void SetNetCode( int aNetCode ) { m_netCode = aNetCode; } /** - * Function GetNetname - * @return const wxString&, a reference to the full netname + * @return the full netname. */ const wxString& GetNetname() const { return m_netname; } /** - * Function GetShortNetname - * @return const wxString &, a reference to the short netname + * @return the short netname. */ const wxString& GetShortNetname() const { return m_shortNetname; } /** - * Function SetNetname - * Sets the long netname to \a aNetName, and the short netname to the last token in + * Set the long netname to \a aNetName, and the short netname to the last token in * the long netname's path. */ void SetNetname( const wxString& aNewName ) @@ -162,8 +141,7 @@ public: void SetIsCurrent( bool isCurrent ) { m_isCurrent = isCurrent; } /** - * Function GetMsgPanelInfo - * returns the information about the #NETINFO_ITEM in \a aList to display in the + * Return the information about the #NETINFO_ITEM in \a aList to display in the * message panel. * * @param aList is the list in which to place the status information. @@ -171,8 +149,7 @@ public: void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; /** - * Function Clear - * sets all fields to their defaults values. + * Set all fields to their default values. */ void Clear() { @@ -183,6 +160,21 @@ public: { return m_parent; } + +private: + friend class NETINFO_LIST; + + int m_netCode; ///< A number equivalent to the net name. + wxString m_netname; ///< Full net name like /sheet/subsheet/vout used by Eeschema. + wxString m_shortNetname; ///< short net name, like vout from /sheet/subsheet/vout. + + NETCLASSPTR m_netClass; + + bool m_isCurrent; ///< Indicates the net is currently in use. We still store + ///< those that are not during a session for undo/redo and to + ///< keep netclass membership information. + + BOARD* m_parent; ///< The parent board the net belongs to. }; @@ -196,8 +188,7 @@ public: /** - * Function SetBoard - * Sets a BOARD object that is used to prepare the net code map. + * Set a BOARD object that is used to prepare the net code map. */ void SetBoard( const BOARD* aBoard ) { @@ -206,23 +197,24 @@ public: } /** - * Function Update - * Prepares a mapping for net codes so they can be saved as consecutive numbers. + * Prepare a mapping for net codes so they can be saved as consecutive numbers. + * * To retrieve a mapped net code, use translateNet() function after calling this. */ void Update(); /** - * Function Translate - * Translates net number according to the map prepared by Update() function. It - * allows one to have items stored with consecutive net codes. + * Translate net number according to the map prepared by Update() function. + * + * It allows one to have items stored with consecutive net codes. + * * @param aNetCode is an old net code. * @return Net code that follows the mapping. */ int Translate( int aNetCode ) const; - ///> Wrapper class, so you can iterate through NETINFO_ITEM*s, not - ///> std::pair + ///< Wrapper class, so you can iterate through NETINFO_ITEM*s, not + ///< std::pair class iterator { public: @@ -268,10 +260,10 @@ public: }; /** - * Function begin() - * Returns iterator to the first entry in the mapping. - * NOTE: The entry is a pointer to the original NETINFO_ITEM object, this it contains - * not mapped net code. + * Return iterator to the first entry in the mapping. + * + * @note The entry is a pointer to the original NETINFO_ITEM object, this it contains + * not mapped net code. */ iterator begin() const { @@ -279,10 +271,10 @@ public: } /** - * Function end() - * Returns iterator to the last entry in the mapping. - * NOTE: The entry is a pointer to the original NETINFO_ITEM object, this it contains - * not mapped net code. + * Return iterator to the last entry in the mapping. + * + * @note The entry is a pointer to the original NETINFO_ITEM object, this it contains + * not mapped net code. */ iterator end() const { @@ -290,7 +282,6 @@ public: } /** - * Function GetSize * @return Number of mapped nets (i.e. not empty nets for a given BOARD object). */ int GetSize() const @@ -299,9 +290,9 @@ public: } private: - const BOARD* m_board; ///> Board for which mapping is prepared - std::map m_netMapping; ///> Map that allows saving net codes with consecutive - ///> numbers (for compatibility reasons) + const BOARD* m_board; ///< Board for which mapping is prepared + std::map m_netMapping; ///< Map that allows saving net codes with consecutive + ///< numbers (for compatibility reasons) }; @@ -319,9 +310,7 @@ DECL_MAP_FOR_SWIG( NETCODES_MAP, int, NETINFO_ITEM* ) #endif /** - * NETINFO_LIST - * is a container class for NETINFO_ITEM elements, which are the nets. That makes - * this class a container for the nets. + * Container for #NETINFO_ITEM elements, which are the nets. */ class NETINFO_LIST { @@ -332,43 +321,37 @@ public: ~NETINFO_LIST(); /** - * Function GetItem - * @param aNetCode = netcode to identify a given NETINFO_ITEM - * @return NETINFO_ITEM* - by \a aNetCode, or NULL if not found + * @param aNetCode netcode to identify a given #NETINFO_ITEM. + * @return net item by \a aNetCode, or NULL if not found. */ NETINFO_ITEM* GetNetItem( int aNetCode ) const; /** - * Function GetItem - * @param aNetName = net name to identify a given NETINFO_ITEM - * @return NETINFO_ITEM* - by \a aNetName, or NULL if not found + * @param aNetName net name to identify a given #NETINFO_ITEM. + * @return net item by \a aNetName, or NULL if not found. */ NETINFO_ITEM* GetNetItem( const wxString& aNetName ) const; /** - * Function GetNetCount - * @return the number of nets ( always >= 1 ) - * because the first net is the "not connected" net and always exists + * @return the number of nets ( always >= 1 ) because the first net is the "not connected" + * net and always exists */ unsigned GetNetCount() const { return m_netNames.size(); } /** - * Function AppendNet - * adds \a aNewElement to the end of the net list. Negative net code means it is going to be + * Add \a aNewElement to the end of the net list. Negative net code means it is going to be * auto-assigned. */ void AppendNet( NETINFO_ITEM* aNewElement ); /** - * Function RemoveNet - * Removes a new from the net list. + * Remove a net from the net list. */ void RemoveNet( NETINFO_ITEM* aNet ); void RemoveUnusedNets(); /** - * Function GetPadCount - * @return the number of pads in board + * @return the number of pads in board. */ /// Return the name map, at least for python. @@ -377,16 +360,16 @@ public: /// Return the netcode map, at least for python. const NETCODES_MAP& NetsByNetcode() const { return m_netCodes; } - ///> Constant that holds the "unconnected net" number (typically 0) - ///> all items "connected" to this net are actually not connected items + ///< Constant that holds the "unconnected net" number (typically 0) + ///< all items "connected" to this net are actually not connected items static const int UNCONNECTED; - ///> Constant that forces initialization of a netinfo item to the NETINFO_ITEM ORPHANED - ///> (typically -1) when calling SetNetCode od board connected items + ///< Constant that forces initialization of a netinfo item to the NETINFO_ITEM ORPHANED + ///< (typically -1) when calling SetNetCode on board connected items. static const int ORPHANED; - ///> NETINFO_ITEM meaning that there was no net assigned for an item, as there was no - ///> board storing net list available. + ///< NETINFO_ITEM meaning that there was no net assigned for an item, as there was no + ///< board storing net list available. static NETINFO_ITEM* OrphanedItem() { static NETINFO_ITEM* g_orphanedItem; @@ -402,8 +385,8 @@ public: #endif #ifndef SWIG - ///> Wrapper class, so you can iterate through NETINFO_ITEM*s, not - ///> std::pair + ///< Wrapper class, so you can iterate through NETINFO_ITEM*s, not + ///< std::pair class iterator { public: @@ -468,25 +451,22 @@ public: private: /** - * Function clear - * deletes the list of nets (and free memory) + * Delete the list of nets (and free memory). */ void clear(); /** - * Function buildListOfNets - * builds or rebuilds the list of NETINFO_ITEMs + * Rebuild the list of NETINFO_ITEMs + * * The list is sorted by names. */ void buildListOfNets(); /** - * Function getFreeNetCode - * returns the first available net code that is not used by any other net. + * Return the first available net code that is not used by any other net. */ int getFreeNetCode(); -private: BOARD* m_parent; NETNAMES_MAP m_netNames; ///< map of , is NETINFO_ITEM owner diff --git a/pcbnew/netlist_reader/board_netlist_updater.h b/pcbnew/netlist_reader/board_netlist_updater.h index 40c7341783..d6b2d931ed 100644 --- a/pcbnew/netlist_reader/board_netlist_updater.h +++ b/pcbnew/netlist_reader/board_netlist_updater.h @@ -11,7 +11,7 @@ * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck * Copyright (C) 2011 Wayne Stambaugh * - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -44,8 +44,7 @@ class PCB_EDIT_FRAME; #include /** - * BOARD_NETLIST_UPDATER - * updates the #BOARD with a new netlist. + * Update the #BOARD with a new netlist. * * The changes are made to the board are as follows they are not disabled in the status * settings in the #NETLIST: @@ -76,53 +75,53 @@ public: ~BOARD_NETLIST_UPDATER(); /** - * Function UpdateNetlist() + * Update the board's components according to the new netlist. + * + * See #BOARD_NETLIST_UPDATER class description for the details of the process. * - * Updates the board's components according to the new netlist. - * See BOARD_NETLIST_UPDATER class description for the details of the process. * @param aNetlist the new netlist * @return true if process was completed successfully */ bool UpdateNetlist( NETLIST& aNetlist ); - ///> Sets the reporter object + ///< Set the reporter object. void SetReporter( REPORTER* aReporter ) { m_reporter = aReporter; } - ///> Enables "delete single pad nets" option + ///< Enable "delete single pad nets" option. void SetDeleteSinglePadNets( bool aEnabled ) { m_deleteSinglePadNets = aEnabled; } - ///> Enables warning option if a connectable pad is not found in netlist - ///> connectable = pad with a name and on a copper layer + ///< Enable warning option if a connectable pad is not found in netlist + ///< connectable = pad with a name and on a copper layer. void SetWarnPadNoNetInNetlist( bool aEnabled ) { m_warnForNoNetPads = aEnabled; } - ///> Enables dry run mode (just report, no changes to PCB) + ///< Enable dry run mode (just report, no changes to PCB). void SetIsDryRun( bool aEnabled ) { m_isDryRun = aEnabled; } - ///> Enables replacing footprints with new ones + ///< Enable replacing footprints with new ones. void SetReplaceFootprints( bool aEnabled ) { m_replaceFootprints = aEnabled; } - ///> Enables removing unused components + ///< Enable removing unused components. void SetDeleteUnusedComponents( bool aEnabled ) { m_deleteUnusedComponents = aEnabled; } - ///> Enables component lookup by timestamp instead of reference + ///< Enable component lookup by timestamp instead of reference. void SetLookupByTimestamp( bool aEnabled ) { m_lookupByTimestamp = aEnabled; @@ -178,7 +177,7 @@ private: bool m_isDryRun; bool m_replaceFootprints; bool m_lookupByTimestamp; - bool m_warnForNoNetPads; //Warn if a connectable pad has no net in netlist (not found). + bool m_warnForNoNetPads; // Warn if a connectable pad has no net in netlist (not found). int m_warningCount; int m_errorCount; diff --git a/pcbnew/pad.h b/pcbnew/pad.h index 1e806fd05e..9f75e3e4db 100644 --- a/pcbnew/pad.h +++ b/pcbnew/pad.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -69,9 +69,10 @@ public: /* * Default layers used for pads, according to the pad type. - * this is default values only, they can be changed for a given pad + * + * This is default values only, they can be changed for a given pad. */ - static LSET PTHMask(); ///< layer set for a through hole pad + static LSET PTHMask(); ///< layer set for a through hole pad static LSET SMDMask(); ///< layer set for a SMD pad on Front layer static LSET ConnSMDMask(); ///< layer set for a SMD pad on Front layer ///< used for edge board connectors @@ -109,22 +110,22 @@ public: bool IsLocked() const override; /** - * Imports the pad settings from aMasterPad. - * The result is "this" has the same settinds (sizes, shapes ... ) - * as aMasterPad - * @param aMasterPad = the template pad + * Import the pad settings from \a aMasterPad. + * + * The result is "this" has the same settings (sizes, shapes ... ) as \a aMasterPad. + * + * @param aMasterPad the template pad. */ void ImportSettingsFrom( const PAD& aMasterPad ); /** - * @return true if the pad has a footprint parent flipped - * (on the back/bottom layer) + * @return true if the pad has a footprint parent flipped on the back/bottom layer. */ bool IsFlipped() const; /** - * Set the pad name (sometimes called pad number, although - * it can be an array reference like AA12). + * Set the pad name (sometimes called pad number, although it can be an array reference + * like AA12). */ void SetName( const wxString& aName ) { m_name = aName; } const wxString& GetName() const { return m_name; } @@ -144,8 +145,6 @@ public: /** * Before we had custom pad shapes it was common to have multiple overlapping pads to * represent a more complex shape. - * @param other - * @return */ bool SameLogicalPadAs( const PAD* other ) const { @@ -176,14 +175,12 @@ public: wxPoint GetPosition() const override { return m_pos; } /** - * Function GetAnchorPadShape * @return the shape of the anchor pad shape, for custom shaped pads. */ PAD_SHAPE_T GetAnchorPadShape() const { return m_anchorPadShape; } /** - * @return the option for the custom pad shape to use as clearance area - * in copper zones + * @return the option for the custom pad shape to use as clearance area in copper zones. */ CUST_PAD_SHAPE_IN_ZONE GetCustomShapeInZoneOpt() const { @@ -191,8 +188,8 @@ public: } /** - * Set the option for the custom pad shape to use as clearance area - * in copper zones + * Set the option for the custom pad shape to use as clearance area in copper zones. + * * @param aOption is the clearance area shape CUST_PAD_SHAPE_IN_ZONE option */ void SetCustomShapeInZoneOpt( CUST_PAD_SHAPE_IN_ZONE aOption ) @@ -201,10 +198,10 @@ public: } /** - * Function SetAnchorPadShape - * Set the shape of the anchor pad for custm shped pads. - * @param the shape of the anchor pad shape( currently, only - * PAD_SHAPE_RECT or PAD_SHAPE_CIRCLE. + * Set the shape of the anchor pad for custom shaped pads. + * + * @param aShape is the shape of the anchor pad shape( currently, only #PAD_SHAPE_RECT or + * #PAD_SHAPE_CIRCLE. */ void SetAnchorPadShape( PAD_SHAPE_T aShape ) { @@ -214,8 +211,6 @@ public: /** * @return true if the pad is on any copper layer, false otherwise. - * pads can be only on tech layers to build special pads. - * they are therefore not always on a copper layer */ bool IsOnCopperLayer() const override { @@ -257,12 +252,12 @@ public: * Has meaning only for custom shape pads. * add a free shape to the shape list. * the shape can be - * a polygon (outline can have a thickness) - * a thick segment - * a filled circle (thickness == 0) or ring - * a filled rect (thickness == 0) or rectangular outline - * a arc - * a bezier curve + * - a polygon (outline can have a thickness) + * - a thick segment + * - a filled circle (thickness == 0) or ring + * - a filled rect (thickness == 0) or rectangular outline + * - a arc + * - a bezier curve */ void AddPrimitivePoly( const SHAPE_POLY_SET& aPoly, int aThickness, bool aFilled ); void AddPrimitivePoly( const std::vector& aPoly, int aThickness, bool aFilled ); @@ -279,13 +274,14 @@ public: bool GetBestAnchorPosition( VECTOR2I& aPos ); /** - * Merge all basic shapes to a SHAPE_POLY_SET - * Note: The results are relative to the pad position, orientation 0. + * Merge all basic shapes to a #SHAPE_POLY_SET. + * + * @note The results are relative to the pad position, orientation 0. */ void MergePrimitivesAsPolygon( SHAPE_POLY_SET* aMergedPolygon, PCB_LAYER_ID aLayer ) const; /** - * clear the basic shapes list + * Clear the basic shapes list. */ void DeletePrimitivesList(); @@ -301,7 +297,7 @@ public: /** * Flip (mirror) the primitives left to right or top to bottom, around the anchor position - * in custom pads + * in custom pads. */ void FlipPrimitives( bool aFlipLeftRight ); @@ -312,7 +308,7 @@ public: void ReplacePrimitives( const std::vector>& aPrimitivesList ); /** - * Import a custom shape primites list (composed of basic shapes) and add items to the + * Import a custom shape primitive list (composed of basic shapes) and add items to the * current list. Copies the input, which is not altered. */ void AppendPrimitives( const std::vector>& aPrimitivesList ); @@ -323,10 +319,11 @@ public: void AddPrimitive( PCB_SHAPE* aPrimitive ); /** - * Function SetOrientation - * sets the rotation angle of the pad. - * @param aAngle in tenths of degrees. If it is outside of 0 - 3600, then it will be - * normalized before being saved. + * Set the rotation angle of the pad. + * + * If \a aAngle is outside of 0 - 3600, then it will be normalized. + * + * @param aAngle in tenths of degrees. */ void SetOrientation( double aAngle ); @@ -336,8 +333,7 @@ public: void SetOrientationDegrees( double aOrientation ) { SetOrientation( aOrientation*10.0 ); } /** - * Function GetOrientation - * returns the rotation angle of the pad in a variety of units (the basic call returns + * Return the rotation angle of the pad in a variety of units (the basic call returns * tenths of degrees). */ double GetOrientation() const { return m_orient; } @@ -369,7 +365,10 @@ public: // We don't currently have an attribute for APERTURE, and adding one will change the file // format, so for now just infer a copper-less pad to be an APERTURE pad. - bool IsAperturePad() const { return ( m_layerMask & LSET::AllCuMask() ).none(); } + bool IsAperturePad() const + { + return ( m_layerMask & LSET::AllCuMask() ).none(); + } void SetPadToDieLength( int aLength ) { m_lengthPadToDie = aLength; } int GetPadToDieLength() const { return m_lengthPadToDie; } @@ -388,13 +387,13 @@ public: void SetLocalSolderPasteMarginRatio( double aRatio ) { m_localSolderPasteMarginRatio = aRatio; } /** - * Function TransformShapeWithClearanceToPolygon * Convert the pad shape to a closed polygon. Circles and arcs are approximated by segments. - * @param aCornerBuffer = a buffer to store the polygon - * @param aClearanceValue = the clearance around the pad - * @param aMaxError = maximum error from true when converting arcs - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? - * @param ignoreLineWidth = used for edge cuts where the line width is only for visualization + * + * @param aCornerBuffer a buffer to store the polygon. + * @param aClearanceValue the clearance around the pad. + * @param aMaxError maximum error from true when converting arcs. + * @param aErrorLoc should the approximation error be placed outside or inside the polygon? + * @param ignoreLineWidth used for edge cuts where the line width is only for visualization. */ void TransformShapeWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, PCB_LAYER_ID aLayer, int aClearanceValue, @@ -402,13 +401,13 @@ public: bool ignoreLineWidth = false ) const override; /** - * Function TransformHoleWithClearanceToPolygon - * Build the Corner list of the polygonal drill shape in the board coordinate system. - * @param aCornerBuffer = a buffer to fill. - * @param aInflateValue = the clearance or margin value. - * @param aError = maximum deviation of an arc from the polygon approximation + * Build the corner list of the polygonal drill shape in the board coordinate system. + * + * @param aCornerBuffer a buffer to fill. + * @param aInflateValue the clearance or margin value. + * @param aError maximum deviation of an arc from the polygon approximation. * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? - * @return false if the pad has no hole, true otherwise + * @return false if the pad has no hole, true otherwise. */ bool TransformHoleWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, int aInflateValue, int aError, ERROR_LOC aErrorLoc ) const; @@ -419,54 +418,47 @@ public: const std::shared_ptr& GetEffectivePolygon() const; /** - * Function GetEffectiveHoleShape - * Returns a SHAPE object representing the pad's hole. + * Return a SHAPE object representing the pad's hole. */ const SHAPE_SEGMENT* GetEffectiveHoleShape() const; /** - * Function GetBoundingRadius - * returns the radius of a minimum sized circle which fully encloses this pad. + * Return the radius of a minimum sized circle which fully encloses this pad. + * * The center is the pad position NOT THE SHAPE POS! */ int GetBoundingRadius() const; /** - * Function GetLocalClearanceOverrides - * returns any local clearance overrides set in the "classic" (ie: pre-rule) system. - * @param aSource [out] optionally reports the source as a user-readable string - * @return int - the clearance in internal units. + * Return any local clearance overrides set in the "classic" (ie: pre-rule) system. + * + * @param aSource [out] optionally reports the source as a user-readable string. + * @return the clearance in internal units. */ int GetLocalClearanceOverrides( wxString* aSource ) const override; - // Mask margins handling: - /** - * Function GetSolderMaskMargin * @return the margin for the solder mask layer - * usually > 0 (mask shape bigger than pad) - * For pads also on copper layers, the value (used to build a default shape) is - * 1 - the local value - * 2 - if 0, the parent footprint value - * 3 - if 0, the global value - * For pads NOT on copper layers, the value is the local value because there is no default - * shape to build + * + * Usually > 0 (mask shape bigger than pad). For pads **not** on copper layers, the value + * is the local value because there is no default shape to build. For pads also on copper + * layers, the value (used to build a default shape) is: + * 1 the local value + * 2 if 0, the parent footprint value + * 3 if 0, the global value */ int GetSolderMaskMargin() const; /** - * Function GetSolderPasteMargin - * @return the margin for the solder mask layer - * usually < 0 (mask shape smaller than pad) - * because the margin can be dependent on the pad size, the margin has a x and a y value + * Usually < 0 (mask shape smaller than pad)because the margin can be dependent on the pad + * size, the margin has a x and a y value. For pads **not** on copper layers, the value is + * the local value because there is no default shape to build. For pads also on copper + * layers, the value (used to build a default shape) is: + * 1 the local value + * 2 if 0, the parent footprint value + * 3 if 0, the global value * - * For pads also on copper layers, the value (used to build a default shape) is - * 1 - the local value - * 2 - if 0, the parent footprint value - * 3 - if 0, the global value - * - * For pads NOT on copper layers, the value is the local value because there is - * no default shape to build + * @return the margin for the solder mask layer. */ wxSize GetSolderPasteMargin() const; @@ -476,6 +468,7 @@ public: /** * Return the zone connection in effect (either locally overridden or overridden in the * parent footprint). + * * Optionally reports on the source of the property (pad, parent footprint or zone). */ ZONE_CONNECTION GetEffectiveZoneConnection( wxString* aSource = nullptr ) const; @@ -483,7 +476,6 @@ public: /** * Set the width of the thermal spokes connecting the pad to a zone. If != 0 this will * override similar settings in the parent footprint and zone. - * @param aWidth */ void SetThermalSpokeWidth( int aWidth ) { m_thermalWidth = aWidth; } int GetThermalSpokeWidth() const { return m_thermalWidth; } @@ -502,8 +494,8 @@ public: int GetEffectiveThermalGap( wxString* aSource = nullptr ) const; /** - * Function SetRoundRectCornerRadius - * has meaning only for rounded rect pads + * Has meaning only for rounded rectangle pads. + * * @return The radius of the rounded corners for this pad. */ void SetRoundRectCornerRadius( double aRadius ); @@ -512,7 +504,8 @@ public: wxPoint ShapePos() const; /** - * has meaning only for rounded rect pads + * Has meaning only for rounded rectangle pads. + * * Set the ratio between the smaller X or Y size and the rounded corner radius. * Cannot be > 0.5; the normalized IPC-7351C value is 0.25 */ @@ -520,7 +513,8 @@ public: double GetRoundRectRadiusRatio() const { return m_roundedCornerScale; } /** - * has meaning only for chamfered rect pads + * Has meaning only for chamfered rectangular pads. + * * Set the ratio between the smaller X or Y size and chamfered corner size. * Cannot be < 0.5. */ @@ -528,30 +522,32 @@ public: double GetChamferRectRatio() const { return m_chamferScale; } /** - * has meaning only for chamfered rect pads - * set the position of the chamfers for orientation 0. - * @param aPositions a bit-set of RECT_CHAMFER_POSITIONS + * Has meaning only for chamfered rectangular pads. + * + * Set the position of the chamfers for orientation 0. + * + * @param aPositions a bit-set of #RECT_CHAMFER_POSITIONS. */ void SetChamferPositions( int aPositions ) { m_chamferPositions = aPositions; } int GetChamferPositions() const { return m_chamferPositions; } /** - * Function GetSubRatsnest - * @return int - the netcode + * @return the netcode. */ int GetSubRatsnest() const { return m_subRatsnest; } void SetSubRatsnest( int aSubRatsnest ) { m_subRatsnest = aSubRatsnest; } /** - * Sets the unconnected removal property. If true, the copper is removed on zone fill - * or when specifically requested when the pad is not connected on a layer. This requires - * that there be a through hole. + * Set the unconnected removal property. + * + * If true, the copper is removed on zone fill or when specifically requested when the pad + * is not connected on a layer. This requires that there be a through hole. */ void SetRemoveUnconnected( bool aSet ) { m_removeUnconnectedLayer = aSet; } bool GetRemoveUnconnected() const { return m_removeUnconnectedLayer; } /** - * Sets whether we keep the top and bottom connections even if they are not connected + * Set whether we keep the top and bottom connections even if they are not connected. */ void SetKeepTopBottom( bool aSet ) { m_keepTopBottomLayer = aSet; } bool GetKeepTopBottom() const { return m_keepTopBottomLayer; } @@ -564,7 +560,8 @@ public: } /** - * Checks to see whether the pad should be flashed on the specific layer + * Check to see whether the pad should be flashed on the specific layer. + * * @param aLayer Layer to check for connectivity * @param aIncludeZones We include zones in potentially connected elements when drawing * @return true if connected by pad or track (or optionally zone) @@ -572,10 +569,12 @@ public: bool FlashLayer( int aLayer, bool aIncludeZones = false ) const; /** - * Checks to see if the pad should be flashed to any of the layers in the set + * Check to see if the pad should be flashed to any of the layers in the set. + * * @param aLayers set of layers to check the via against * @param aIncludeZones We include zones in potentially connected elements when drawing - * @return true if connected by pad or track (or optionally zone) on any of the associated layers + * @return true if connected by pad or track (or optionally zone) on any of the associated + * layers */ bool FlashLayer( LSET aLayers, bool aIncludeZones = false ) const; @@ -588,22 +587,22 @@ public: } /** - * Function GetBoundingBox * The bounding box is cached, so this will be efficient most of the time. */ const EDA_RECT GetBoundingBox() const override; - ///> Set absolute coordinates. + ///< Set absolute coordinates. void SetDrawCoord(); //todo: Remove SetLocalCoord along with m_pos - ///> Set relative coordinates. + ///< Set relative coordinates. void SetLocalCoord(); /** - * Function Compare - * compares two pads and return 0 if they are equal. - * @return int - <0 if left less than right, 0 if equal, >0 if left greater than right. + * Compare two pads and return 0 if they are equal. + * + * @return less than 0 if left less than right, 0 if equal, or greater than 0 if left + * greater than right. */ static int Compare( const PAD* padref, const PAD* padcmp ); @@ -621,13 +620,11 @@ public: BITMAP_DEF GetMenuImage() const override; /** - * Function ShowPadShape - * @return the GUI-appropriate name of the shape + * @return the GUI-appropriate name of the shape. */ wxString ShowPadShape() const; /** - * Function ShowPadAttr * @return the GUI-appropriate description of the pad type (attribute) : Std, SMD ... */ wxString ShowPadAttr() const; @@ -635,7 +632,8 @@ public: EDA_ITEM* Clone() const override; /** - * same as Clone, but returns a PAD item. + * Same as Clone, but returns a PAD item. + * * Useful mainly for python scripts, because Clone returns an EDA_ITEM. */ PAD* ClonePad() const @@ -644,7 +642,7 @@ public: } /** - * Rebuilds the effective shape cache (and bounding box and radius) for the pad and clears + * Rebuild the effective shape cache (and bounding box and radius) for the pad and clears * the dirty bit. */ void BuildEffectiveShapes( PCB_LAYER_ID aLayer ) const; @@ -710,7 +708,7 @@ private: PAD_DRILL_SHAPE_T m_drillShape; // PAD_DRILL_SHAPE_CIRCLE, PAD_DRILL_SHAPE_OBLONG - double m_roundedCornerScale; // Scaling factor of min(width, hieght) to corner + double m_roundedCornerScale; // Scaling factor of min(width, height) to corner // radius, default 0.25 double m_chamferScale; // Scaling factor of min(width, height) to chamfer // size, default 0.25 @@ -746,11 +744,14 @@ private: int m_lengthPadToDie; // Length net from pad to die, inside the package - bool m_removeUnconnectedLayer; // If true, the pad copper is removed for layers that are not connected - bool m_keepTopBottomLayer; // When removing unconnected pads, keep the top and bottom pads + ///< If true, the pad copper is removed for layers that are not connected. + bool m_removeUnconnectedLayer; + + ///< When removing unconnected pads, keep the top and bottom pads. + bool m_keepTopBottomLayer; /* - * Pad clearances, margins, etc. exist in a hiearchy. If a given level is specified then + * Pad clearances, margins, etc. exist in a hierarchy. If a given level is specified then * the remaining levels are NOT consulted. * * LEVEL 1: (highest priority) local overrides (pad, footprint, etc.) diff --git a/pcbnew/pcb_base_edit_frame.h b/pcbnew/pcb_base_edit_frame.h index c00f044ed9..af92b9c805 100644 --- a/pcbnew/pcb_base_edit_frame.h +++ b/pcbnew/pcb_base_edit_frame.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -54,96 +55,90 @@ public: * then creates a new footprint library at that location. * If library exists, user is warned about that, and is given a chance * to abort the new creation, and in that case existing library is first deleted. - * @param aProposedName is the inital path and filename shown in the file chooser dialog * - * @return wxString - the newly created library path if library was successfully - * created, else wxEmptyString because user aborted or error. + * @param aProposedName is the initial path and filename shown in the file chooser dialog. + * @return The newly created library path if library was successfully created, else + * wxEmptyString because user aborted or error. */ wxString CreateNewLibrary( const wxString& aLibName = wxEmptyString, const wxString& aProposedName = wxEmptyString ); /** - * Function AddLibrary * Add an existing library to either the global or project library table. + * * @param aFileName the library to add; a file open dialog will be displayed if empty. - * @return true if successfully added + * @return true if successfully added. */ bool AddLibrary(const wxString& aLibName = wxEmptyString); /** - * Function OnEditItemRequest - * Install the corresponding dialog editor for the given item - * @param aDC = the current device context - * @param aItem = a pointer to the BOARD_ITEM to edit + * Install the corresponding dialog editor for the given item. + * + * @param aDC the current device context. + * @param aItem a pointer to the BOARD_ITEM to edit. */ virtual void OnEditItemRequest( BOARD_ITEM* aItem ) = 0; - // Undo buffer handling - /** - * Function SaveCopyInUndoList - * Creates a new entry in undo list of commands. - * add a picker to handle aItemToCopy - * @param aItemToCopy = the board item modified by the command to undo - * @param aTypeCommand = command type (see enum UNDO_REDO) - * @param aTransformPoint = the reference point of the transformation, for - * commands like move + * Create a new entry in undo list of commands. + * + * Add a picker to handle \a aItemToCopy. + * + * @param aItemToCopy the board item modified by the command to undo. + * @param aTypeCommand command type (see enum UNDO_REDO). + * @param aTransformPoint the reference point of the transformation, for commands like move */ void SaveCopyInUndoList( EDA_ITEM* aItemToCopy, UNDO_REDO aTypeCommand, const wxPoint& aTransformPoint = wxPoint( 0, 0 ) ) override; /** - * Function SaveCopyInUndoList - * Creates a new entry in undo list of commands. - * add a list of pickers to handle a list of items - * @param aItemsList = the list of items modified by the command to undo - * @param aTypeCommand = command type (see enum UNDO_REDO) - * @param aTransformPoint = the reference point of the transformation, - * for commands like move + * Create a new entry in undo list of commands. + * + * Add a list of pickers to handle a list of items. + * + * @param aItemsList the list of items modified by the command to undo. + * @param aTypeCommand command type (see enum UNDO_REDO). + * @param aTransformPoint the reference point of the transformation for commands like move. */ void SaveCopyInUndoList( const PICKED_ITEMS_LIST& aItemsList, UNDO_REDO aTypeCommand, const wxPoint& aTransformPoint = wxPoint( 0, 0 ) ) override; /** - * Function RestoreCopyFromRedoList - * Redo the last edit: + * Redo the last edit: * - Save the current board in Undo list * - Get an old version of the board from Redo list - * @return none */ void RestoreCopyFromRedoList( wxCommandEvent& aEvent ); /** - * Function RestoreCopyFromUndoList - * Undo the last edit: + * Undo the last edit: * - Save the current board in Redo list * - Get an old version of the board from Undo list - * @return none */ void RestoreCopyFromUndoList( wxCommandEvent& aEvent ); /** - * Performs an undo of the last edit WITHOUT logging a corresponding redo. Used to cancel + * Perform an undo of the last edit **without** logging a corresponding redo. Used to cancel * an in-progress operation. */ void RollbackFromUndo(); /** - * Function PutDataInPreviousState * Used in undo or redo command. - * Put data pointed by List in the previous state, i.e. the state memorized by List - * @param aList = a PICKED_ITEMS_LIST pointer to the list of items to undo/redo - * @param aRedoCommand = a bool: true for redo, false for undo - * @param aRebuildRatsnet = a bool: true to rebuild ratsnest (normal use), false to just - * retrieve last state (used in abort commands that do not need to rebuild ratsnest) + * + * Put data pointed by List in the previous state, i.e. the state memorized by \a aList. + * + * @param aList a PICKED_ITEMS_LIST pointer to the list of items to undo/redo. + * @param aRedoCommand true for redo, false for undo. + * @param aRebuildRatsnet a bool: true to rebuild ratsnest (normal use), false to just + * retrieve last state (used in abort commands that do not need + * to rebuild ratsnest). */ - void PutDataInPreviousState( PICKED_ITEMS_LIST* aList, - bool aRedoCommand, - bool aRebuildRatsnet = true ); + void PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRedoCommand, + bool aRebuildRatsnet = true ); /** - * Function UndoRedoBlocked - * Checks if the undo and redo operations are currently blocked. + * Check if the undo and redo operations are currently blocked. */ bool UndoRedoBlocked() const { @@ -151,8 +146,7 @@ public: } /** - * Function UndoRedoBlock - * Enables/disable undo and redo operations. + * Enable/disable undo and redo operations. */ void UndoRedoBlock( bool aBlock = true ) { @@ -160,35 +154,31 @@ public: } /** - * Function SetGridVisibility() - * * Override this function in the PCB_BASE_EDIT_FRAME to refill the layer widget * - * @param aVisible = true if the grid must be shown + * @param aVisible true if the grid must be shown. */ void SetGridVisibility( bool aVisible ) override; void SetObjectVisible( GAL_LAYER_ID aLayer, bool aVisible = true ); /** - * Function GetRotationAngle() - * Returns the angle used for rotate operations. + * Return the angle used for rotate operations. */ int GetRotationAngle() const { return m_rotationAngle; } /** - * Function SetRotationAngle() - * Sets the angle used for rotate operations. + * Set the angle used for rotate operations. */ void SetRotationAngle( int aRotationAngle ); void ShowTextPropertiesDialog( BOARD_ITEM* aText ); void ShowGraphicItemPropertiesDialog( BOARD_ITEM* aItem ); - ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas() + ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas() void ActivateGalCanvas() override; - ///> @copydoc PCB_BASE_FRAME::SetBoard() + ///< @copydoc PCB_BASE_FRAME::SetBoard() virtual void SetBoard( BOARD* aBoard ) override; COLOR_SETTINGS* GetColorSettings() const override; @@ -200,23 +190,23 @@ public: // use EDA_BASE_FRAME::PushCommandToRedoList( PICKED_ITEMS_LIST* aItem ) /** - * Function ClearUndoORRedoList - * free the undo or redo list from List element - * Wrappers are deleted. - * datas pointed by wrappers are deleted if not in use in schematic - * i.e. when they are copy of a schematic item or they are no more in use - * (DELETED) - * @param whichList = the UNDO_REDO_CONTAINER to clear - * @param aItemCount = the count of items to remove. < 0 for all items - * items are removed from the beginning of the list. - * So this function can be called to remove old commands + * Free the undo or redo list from List element. + * + * Wrappers are deleted. Data pointed by wrappers are deleted if not in use in schematic + * i.e. when they are copy of a schematic item or they are no more in use (DELETED). + * Items are removed from the beginning of the list so this function can be called to + * remove old commands. + * + * @param whichList the #UNDO_REDO_CONTAINER to clear. + * @param aItemCount the count of items to remove. < 0 for all items. */ void ClearUndoORRedoList( UNDO_REDO_LIST whichList, int aItemCount = -1 ) override; /** - * Returns the absolute path to the design rules file for the currently-loaded board. - * Note that there is no guarantee that this file actually exists and can be opened! - * NOTE: only really makes sense from PcbNew, but is needed in PCB_BASE_EDIT_FRAME::SetBoard + * Return the absolute path to the design rules file for the currently-loaded board. + * + * @note There is no guarantee that this file actually exists and can be opened! It only + * makes sense from PcbNew but is needed in #PCB_BASE_EDIT_FRAME::SetBoard. */ wxString GetDesignRulesPath(); diff --git a/pcbnew/pcb_draw_panel_gal.h b/pcbnew/pcb_draw_panel_gal.h index 9f2a21c67c..c18c155df8 100644 --- a/pcbnew/pcb_draw_panel_gal.h +++ b/pcbnew/pcb_draw_panel_gal.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -45,17 +47,17 @@ public: virtual ~PCB_DRAW_PANEL_GAL(); /** - * Function DisplayBoard - * adds all items from the current board to the VIEW, so they can be displayed by GAL. + * Add all items from the current board to the VIEW, so they can be displayed by GAL. + * * @param aBoard is the PCB to be loaded. */ void DisplayBoard( BOARD* aBoard ); /** - * Function SetWorksheet - * Sets (or updates) worksheet used by the draw panel. - * @param aWorksheet is the worksheet to be used. - * The object is then owned by PCB_DRAW_PANEL_GAL. + * Set (or updates) worksheet used by the draw panel. + * + * @param aWorksheet is the worksheet to be used. The object is then owned by + * #PCB_DRAW_PANEL_GAL. */ void SetWorksheet( KIGFX::WS_PROXY_VIEW_ITEM* aWorksheet ); @@ -63,63 +65,62 @@ public: // TODO(JE) Look at optimizing this out /** - * Updates the color settings in the painter and GAL + * Update the color settings in the painter and GAL. */ void UpdateColors(); - ///> @copydoc EDA_DRAW_PANEL_GAL::SetHighContrastLayer() + ///< @copydoc EDA_DRAW_PANEL_GAL::SetHighContrastLayer() virtual void SetHighContrastLayer( int aLayer ) override { SetHighContrastLayer( static_cast< PCB_LAYER_ID >( aLayer ) ); } - ///> SetHighContrastLayer(), with some extra smarts for PCB + ///< SetHighContrastLayer(), with some extra smarts for PCB. void SetHighContrastLayer( PCB_LAYER_ID aLayer ); - ///> @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer() + ///< @copydoc EDA_DRAW_PANEL_GAL::SetTopLayer() virtual void SetTopLayer( int aLayer ) override { SetTopLayer( static_cast< PCB_LAYER_ID >( aLayer ) ); } - ///> SetTopLayer(), with some extra smarts for PCB + ///< SetTopLayer(), with some extra smarts for PCB. void SetTopLayer( PCB_LAYER_ID aLayer ); /** - * Function SyncLayersVisibility - * Updates "visibility" property of each layer of a given BOARD. + * Update "visibility" property of each layer of a given #BOARD. + * * @param aBoard contains layers visibility settings to be applied. */ void SyncLayersVisibility( const BOARD* aBoard ); - ///> @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo() + ///< @copydoc EDA_DRAW_PANEL_GAL::GetMsgPanelInfo() void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector& aList ) override; - ///> @copydoc EDA_DRAW_PANEL_GAL::OnShow() + ///< @copydoc EDA_DRAW_PANEL_GAL::OnShow() void OnShow() override; bool SwitchBackend( GAL_TYPE aGalType ) override; - ///> Forces refresh of the ratsnest visual representation + ///< Force refresh of the ratsnest visual representation. void RedrawRatsnest(); - ///> @copydoc EDA_DRAW_PANEL_GAL::GetDefaultViewBBox() + ///< @copydoc EDA_DRAW_PANEL_GAL::GetDefaultViewBBox() BOX2I GetDefaultViewBBox() const override; virtual KIGFX::PCB_VIEW* GetView() const override; protected: - - ///> Reassigns layer order to the initial settings. + ///< Reassign layer order to the initial settings. void setDefaultLayerOrder(); - ///> Sets rendering targets & dependencies for layers. + ///< Set rendering targets & dependencies for layers. void setDefaultLayerDeps(); - ///> Currently used worksheet + ///< Currently used worksheet. std::unique_ptr m_worksheet; - ///> Ratsnest view item + ///< Ratsnest view item std::unique_ptr m_ratsnest; }; diff --git a/pcbnew/pcb_edit_frame.h b/pcbnew/pcb_edit_frame.h index 7037e9023e..8b9d2b7edf 100644 --- a/pcbnew/pcb_edit_frame.h +++ b/pcbnew/pcb_edit_frame.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2010 Jean-Pierre Charras, jp.charras@wanadoo.fr - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2010-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -64,8 +64,7 @@ enum LAST_PATH_TYPE : unsigned int; namespace PCB { struct IFACE; } // KIFACE_I is in pcbnew.cpp /** - * PCB_EDIT_FRAME - * is the main frame for Pcbnew. + * The main frame for Pcbnew. * * See also class PCB_BASE_FRAME(): Basic class for Pcbnew and GerbView. */ @@ -99,53 +98,52 @@ protected: LAYER_TOOLBAR_ICON_VALUES m_prevIconVal; - // The Tool Framework initalization + // The Tool Framework initialization void setupTools(); void setupUIConditions() override; /** - * switches currently used canvas (Cairo / OpenGL). + * Switch currently used canvas (Cairo / OpenGL). + * * It also reinit the layers manager that slightly changes with canvases */ void SwitchCanvas( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ) override; #if defined(KICAD_SCRIPTING) && defined(KICAD_SCRIPTING_ACTION_MENU) /** - * Function buildActionPluginMenus * Fill action menu with all registered action plugins */ void buildActionPluginMenus( ACTION_MENU* aActionMenu ); /** - * Function AddActionPluginTools * Append action plugin buttons to main toolbar */ void AddActionPluginTools(); /** - * Function RunActionPlugin - * Executes action plugin's Run() method and updates undo buffer + * Execute action plugin's Run() method and updates undo buffer. + * * @param aActionPlugin action plugin */ void RunActionPlugin( ACTION_PLUGIN* aActionPlugin ); /** - * Function OnActionPluginMenu - * Launched by the menu when an action is called + * Launched by the menu when an action is called. + * * @param aEvent sent by wx */ void OnActionPluginMenu( wxCommandEvent& aEvent); /** - * Function OnActionPluginButton - * Launched by the button when an action is called + * Launched by the button when an action is called. + * * @param aEvent sent by wx */ void OnActionPluginButton( wxCommandEvent& aEvent ); /** - * Function OnActionPluginRefresh - * Refresh plugin list (reload Python plugins) + * Refresh plugin list (reload Python plugins). + * * @param aEvent sent by wx */ void OnActionPluginRefresh( wxCommandEvent& aEvent) @@ -154,8 +152,8 @@ protected: } /** - * Function OnActionPluginRefresh - * Refresh plugin list (reload Python plugins) + * Refresh plugin list (reload Python plugins). + * * @param aEvent sent by wx */ void OnActionPluginShowFolder( wxCommandEvent& aEvent) @@ -164,9 +162,10 @@ protected: } #endif - /** Has meaning only if KICAD_SCRIPTING_WXPYTHON option is - * not defined - * @return the frame name identifier for the python console frame + /** + * Has meaning only if KICAD_SCRIPTING_WXPYTHON option is not defined. + * + * @return the frame name identifier for the python console frame. */ static const wxChar * pythonConsoleNameId() { @@ -182,13 +181,12 @@ protected: } /** - * Updates the state of the GUI after a new board is loaded or created + * Update the state of the GUI after a new board is loaded or created. */ void onBoardLoaded(); /** - * Function doAutoSave - * performs auto save when the board has been modified and not saved within the + * Perform auto save when the board has been modified and not saved within the * auto save interval. * * @return true if the auto save was successful. @@ -196,15 +194,15 @@ protected: bool doAutoSave() override; /** - * Function isautoSaveRequired - * returns true if the board has been modified. + * Return true if the board has been modified. */ bool isAutoSaveRequired() const override; /** * Load the given filename but sets the path to the current project path. - * @param full filepath of file to be imported. - * @param aFileType PCB_FILE_T value for filetype + * + * @param full file path of file to be imported. + * @param aFileType PCB_FILE_T value for file type */ bool importFile( const wxString& aFileName, int aFileType ); @@ -220,18 +218,18 @@ protected: public: PCB_LAYER_BOX_SELECTOR* m_SelLayerBox; // a combo box to display and select active layer - wxChoice* m_SelTrackWidthBox; // a choice box to display and select current track width - wxChoice* m_SelViaSizeBox; // a choice box to display and select current via diameter + + wxChoice* m_SelTrackWidthBox; // a choice box to display and select current track width + wxChoice* m_SelViaSizeBox; // a choice box to display and select current via diameter bool m_show_layer_manager_tools; - bool m_ZoneFillsDirty; // Board has been modified since last zone fill. + bool m_ZoneFillsDirty; // Board has been modified since last zone fill. virtual ~PCB_EDIT_FRAME(); /** - * Function loadFootprints - * loads the footprints for each #COMPONENT in \a aNetlist from the list of libraries. + * Load the footprints for each #SCH_COMPONENT in \a aNetlist from the list of libraries. * * @param aNetlist is the netlist of components to load the footprints into. * @param aReporter is the #REPORTER object to report to. @@ -281,24 +279,24 @@ public: void UpdateUserInterface(); /** - * Execute a remote command send by Eeschema via a socket, - * port KICAD_PCB_PORT_SERVICE_NUMBER (currently 4242) - * this is a virtual function called by EDA_DRAW_FRAME::OnSockRequest(). - * @param cmdline = received command from socket + * Execute a remote command send by Eeschema via a socket, port KICAD_PCB_PORT_SERVICE_NUMBER + * (currently 4242). + * + * This is a virtual function called by EDA_DRAW_FRAME::OnSockRequest(). + * + * @param cmdline is the received command from socket. */ void ExecuteRemoteCommand( const char* cmdline ) override; void KiwayMailIn( KIWAY_EXPRESS& aEvent ) override; /** - * Function ToPlotter * Open a dialog frame to create plot and drill files relative to the current board. */ void ToPlotter( int aID ); /** - * Function SVG_Print - * Shows the Export to SVG file dialog. + * Show the Export to SVG file dialog. */ void ExportSVG( wxCommandEvent& event ); @@ -315,14 +313,12 @@ public: void UpdateViaSizeSelectBox( wxChoice* aViaSizeSelectBox, bool aEdit = true ); /** - * Function GetGridColor() , virtual * @return the color of the grid */ COLOR4D GetGridColor() override; /** - * Function SetGridColor() , virtual - * @param aColor = the new color of the grid + * @param aColor the new color of the grid. */ void SetGridColor( COLOR4D aColor ) override; @@ -332,23 +328,21 @@ public: #if defined(KICAD_SCRIPTING) && defined(KICAD_SCRIPTING_ACTION_MENU) /** - * Function GetActionPluginButtonVisible - * Returns true if button visibility action plugin setting was set to true + * Return true if button visibility action plugin setting was set to true * or it is unset and plugin defaults to true. */ bool GetActionPluginButtonVisible( const wxString& aPluginPath, bool aPluginDefault ); /** - * Function GetOrderedActionPlugins - * Returns ordered list of plugins in sequence in which they should appear on toolbar or in settings + * Return ordered list of plugins in sequence in which they should appear on toolbar or + * in settings */ std::vector GetOrderedActionPlugins(); #endif /** - * Function SaveProjectSettings - * saves changes to the project settings to the project (.pro) file. + * Save changes to the project settings to the project (.pro) file. */ void SaveProjectSettings() override; @@ -366,14 +360,15 @@ public: /** * Get the last path for a particular type. - * @return - Absolute path and file name of the last file successfully read. + * + * @return the absolute path and file name of the last file successfully read. */ wxString GetLastPath( LAST_PATH_TYPE aType ); /** * Set the path of the last file successfully read. * - * Note: the file path is converted to a path relative to the project file path. If + * @note the file path is converted to a path relative to the project file path. If * the path cannot be made relative, than m_lastNetListRead is set to and empty * string. This could happen when the net list file is on a different drive than * the project file. The advantage of relative paths is that is more likely to @@ -403,29 +398,26 @@ public: void ReCreateMenuBar() override; /** - * Re create the layer Box by clearing the old list, and building - * le new one, from the new layers names and cole layers - * @param aForceResizeToolbar = true to resize the parent toolbar - * false if not needed (mainly in parent toolbar creation, - * or when the layers names are not modified) + * Recreate the layer box by clearing the old list and building a new one from the new + * layer names and colors. + * + * @param aForceResizeToolbar true to resize the parent toolbar false if not needed (mainly + * in parent toolbar creation, or when the layers names are not + * modified) */ void ReCreateLayerBox( bool aForceResizeToolbar = true ); /** - * Function OnModify - * must be called after a board change to set the modified flag. - *

- * Reloads the 3D view if required and calls the base PCB_BASE_FRAME::OnModify function + * Must be called after a board change to set the modified flag. + * + * Reload the 3D view if required and calls the base PCB_BASE_FRAME::OnModify function * to update auxiliary information. - *

*/ void OnModify() override; /** - * Function SetActiveLayer - * will change the currently active layer to \a aLayer and also - * update the APPEARANCE_CONTROLS. + * Change the currently active layer to \a aLayer and also update the #APPEARANCE_CONTROLS. */ void SetActiveLayer( PCB_LAYER_ID aLayer ) override; @@ -439,9 +431,8 @@ public: void OnDisplayOptionsChanged() override; /** - * Function IsElementVisible - * tests whether a given element category is visible. Keep this as an - * inline function. + * Test whether a given element category is visible. Keep this as an inline function. + * * @param aElement is from the enum by the same name * @return bool - true if the element is visible. * @see enum GAL_LAYER_ID @@ -449,58 +440,50 @@ public: bool IsElementVisible( GAL_LAYER_ID aElement ) const; /** - * Function SetElementVisibility - * changes the visibility of an element category - * @param aElement is from the enum by the same name - * @param aNewState The new visibility state of the element category - * @see enum PCB_LAYER_ID + * Change the visibility of an element category. + * + * @param aElement is from the enum by the same name. + * @param aNewState The new visibility state of the element category. + * @see enum PCB_LAYER_ID. */ void SetElementVisibility( GAL_LAYER_ID aElement, bool aNewState ); - ///> @copydoc EDA_DRAW_FRAME::UseGalCanvas() + ///< @copydoc EDA_DRAW_FRAME::UseGalCanvas() void ActivateGalCanvas() override; - /** - * Function ShowBoardSetupDialog - */ void ShowBoardSetupDialog( const wxString& aInitialPage = wxEmptyString ); - /* toolbars update UI functions: */ - void PrepareLayerIndicator( bool aForceRebuild = false ); void ToggleLayersManager(); /** - * Function DoGenFootprintsPositionFile - * Creates an ascii footprint position file - * @param aFullFileName = the full file name of the file to create - * @param aUnitsMM = false to use inches, true to use mm in coordinates - * @param aForceSmdItems = true to force all footprints with smd pads in list - * = false to put only footprints with option "INSERT" in list - * @param aTopSide true to list footprints on front (top) side, - * @param aBottomSide true to list footprints on back (bottom) side, - * if aTopSide and aTopSide are true, list footprints on both sides - * @param aFormatCSV = true to use a comma separated file (CSV) format; defautl = false - * @return the number of footprints found on aSide side, - * or -1 if the file could not be created + * Create an ASCII footprint position file. + * + * @param aFullFileName the full file name of the file to create. + * @param aUnitsMM false to use inches, true to use mm in coordinates. + * @param aForceSmdItems true to force all footprints with smd pads in list, + * false to put only footprints with option "INSERT" in list + * @param aTopSide true to list footprints on front (top) side. + * @param aBottomSide true to list footprints on back (bottom) side, if \a aTopSide and + * \a aTopSide are true, list footprints on both sides. + * @param aFormatCSV true to use a comma separated file (CSV) format; default = false + * @return the number of footprints found on aSide side or -1 if the file could not be created. */ int DoGenFootprintsPositionFile( const wxString& aFullFileName, bool aUnitsMM, - bool aForceSmdItems, bool aTopSide, bool aBottomSide, bool aFormatCSV = false ); + bool aForceSmdItems, bool aTopSide, bool aBottomSide, + bool aFormatCSV = false ); /** - * Function GenFootprintsReport - * Calls DoGenFootprintsReport to create a footprint reprot file - * See DoGenFootprintsReport for file format + * Call #DoGenFootprintsReport to create a footprint report file */ void GenFootprintsReport( wxCommandEvent& event ); /** - * Function DoGenFootprintsReport - * Creates an ascii footprint report file giving some infos on footprints - * and board outlines - * @param aFullFilename = the full file name of the file to create - * @param aUnitsMM = false to use inches, true to use mm in coordinates + * Create an ASCII footprint report file giving some infos on footprints and board outlines. + * + * @param aFullFilename the full file name of the file to create + * @param aUnitsMM false to use inches, true to use mm in coordinates * @return true if OK, false if error */ bool DoGenFootprintsReport( const wxString& aFullFilename, bool aUnitsMM ); @@ -511,51 +494,49 @@ public: void OnClearFileHistory( wxCommandEvent& aEvent ); /** - * Function Files_io + * Call #Files_io_from_id with the wxCommandEvent id. + * * @param event is the command event handler. - * do nothing else than call Files_io_from_id with the - * wxCommandEvent id */ void Files_io( wxCommandEvent& event ); /** - * Function Files_io_from_id - * Read and write board files - * @param aId is an event ID ciming from file command events: - * ID_LOAD_FILE - * ID_MENU_RECOVER_BOARD_AUTOSAVE - * ID_NEW_BOARD - * ID_SAVE_BOARD - * ID_COPY_BOARD_AS - * ID_SAVE_BOARD_AS - * Files_io_from_id prepare parameters and calls the specialized function + * Read and write board files according to \a aId. + * + * Valid event IDs are: + * - ID_LOAD_FILE + * - ID_MENU_RECOVER_BOARD_AUTOSAVE + * - ID_NEW_BOARD + * - ID_SAVE_BOARD + * - ID_COPY_BOARD_AS + * - ID_SAVE_BOARD_AS + * + * @param aId is an event ID coming from file command events: */ bool Files_io_from_id( int aId ); /** - * Function OpenProjectFiles (was LoadOnePcbFile) - * loads a KiCad board (.kicad_pcb) from \a aFileName. + * Load a KiCad board (.kicad_pcb) from \a aFileName. * - * @param aFileSet - hold the BOARD file to load, a vector of one element. + * @param aFileSet hold the BOARD file to load, a vector of one element. + * @param aCtl KICTL_ bits, one to indicate that an append of the board file + * \a aFileName to the currently loaded file is desired. + * @see #KIWAY_PLAYER for bit defines. * - * @param aCtl - KICTL_ bits, one to indicate that an append of the board file - * aFileName to the currently loaded file is desired. - * @see #KIWAY_PLAYER for bit defines. - * - * @return bool - false if file load fails, otherwise true. + * @return false if file load fails, otherwise true. bool LoadOnePcbFile( const wxString& aFileName, bool aAppend = false, bool aForceFileDialog = false ); */ bool OpenProjectFiles( const std::vector& aFileSet, int aCtl = 0 ) override; /** - * Function SavePcbFile - * writes the board data structures to \a a aFileName - * Creates backup when requested and update flags (modified and saved flgs) + * Writes the board data structures to \a a aFileName. + * + * Create a backup when requested and update flags (modified and saved flags). * * @param aFileName The file name to write or wxEmptyString to prompt user for * file name. - * @param addToHistory controsl whether or not to add the saved file to the recent file list + * @param addToHistory controls whether or not to add the saved file to the recent file list * @param aChangeProject is true if the project should be changed to the new board filename * @return True if file was saved successfully. */ @@ -563,83 +544,72 @@ public: bool aChangeProject = true ); /** - * Function SavePcbCopy - * writes the board data structures to \a a aFileName - * but unlike SavePcbFile, does not make anything else - * (no backup, borad fliename change, no flag changes ...) - * Used under a project mgr to save under a new name the current board + * Write the board data structures to \a aFileName. * + * Unlike SavePcbFile, does not make anything else (no backup, broad filename change, no + * flag changes ...). Used under a project mgr to save under a new name the current board. * When not under a project mgr, the full SavePcbFile is used. + * * @param aFileName The file name to write. * @param aCreateProject will create an empty project alongside the board file * @return True if file was saved successfully. */ bool SavePcbCopy( const wxString& aFileName, bool aCreateProject = false ); - // BOARD handling - /** - * Function Clear_Pcb - * delete all and reinitialize the current board - * @param aQuery = true to prompt user for confirmation, false to initialize silently - * @param aFinal = if true, we are clearing the board to exit, so don't run more events + * Delete all and reinitialize the current board. + * + * @param aQuery true to prompt user for confirmation, false to initialize silently. + * @param aFinal if true, we are clearing the board to exit, so don't run more events. */ bool Clear_Pcb( bool aQuery, bool aFinal = false ); - ///> @copydoc PCB_BASE_FRAME::SetBoard() + ///< @copydoc PCB_BASE_FRAME::SetBoard() void SetBoard( BOARD* aBoard ) override; - ///> @copydoc PCB_BASE_FRAME::GetModel() + ///< @copydoc PCB_BASE_FRAME::GetModel() BOARD_ITEM_CONTAINER* GetModel() const override; - ///> @copydoc PCB_BASE_FRAME::SetPageSettings() + ///< @copydoc PCB_BASE_FRAME::SetPageSettings() void SetPageSettings( const PAGE_INFO& aPageSettings ) override; /** - * Function RecreateBOMFileFromBoard - * Recreates a .cmp file from the current loaded board - * this is the same as created by CvPcb. - * can be used if this file is lost + * Recreates a .cmp file from the current loaded board. + * + * This is the same as created by CvPcb and can be used if this file is lost. */ void RecreateCmpFileFromBoard( wxCommandEvent& aEvent ); /** - * Function ExportFootprintsToLibrary * Save footprints in a library: - * @param aStoreInNewLib: - * true : save footprints in a existing lib. Existing footprints will be kept - * or updated. - * This lib should be in fp lib table, and is type is .pretty - * false: save footprints in a new lib. It it is an existing lib, - * previous footprints will be removed * - * @param aLibName: - * optional library name to create, stops dialog call. - * must be called with aStoreInNewLib as true + * @param aStoreInNewLib true to save footprints in a existing library. Existing footprints + * will be kept or updated. This library should be in fp lib table, + * and is type is .pretty. False to save footprints in a new library. + * If it is an existing lib, previous footprints will be removed. + * + * @param aLibName optional library name to create, stops dialog call. Must be called with + * \a aStoreInNewLib as true. */ void ExportFootprintsToLibrary( bool aStoreInNewLib, const wxString& aLibName = wxEmptyString, wxString* aLibPath = NULL ); /** - * Function RecreateBOMFileFromBoard - * Creates a BOM file from the current loaded board + * Create a BOM file from the current loaded board. */ void RecreateBOMFileFromBoard( wxCommandEvent& aEvent ); /** - * Function ExportToGenCAD - * creates a file in GenCAD 1.4 format from the current board. + * Create a file in GenCAD 1.4 format from the current board. */ void ExportToGenCAD( wxCommandEvent& event ); /** - * Function OnExportVRML - * will export the current BOARD to a VRML file. + * Export the current BOARD to a VRML file. */ void OnExportVRML( wxCommandEvent& event ); /** - * Function ExportVRML_File * Creates the file(s) exporting current BOARD to a VRML file. * * @note When copying 3D shapes files, the new filename is build from the full path @@ -652,72 +622,66 @@ public: * @note For 3D models built by a 3D modeler, the unit is 0,1 inches. A specific scale * is applied to 3D models to convert them to internal units. * - * @param aFullFileName = the full filename of the file to create - * @param aMMtoWRMLunit = the VRML scaling factor: - * 1.0 to export in mm. 0.001 for meters - * @param aExport3DFiles = true to copy 3D shapes in the subir a3D_Subdir + * @param aFullFileName the full filename of the file to create + * @param aMMtoWRMLunit the VRML scaling factor: 1.0 to export in mm. 0.001 for meters + * @param aExport3DFiles true to copy 3D shapes in the subir a3D_Subdir * @param aUseRelativePaths set to true to use relative paths instead of absolute paths * in the board VRML file URLs. - * @param aUsePlainPCB set to true to export a board with no copper or silkskreen; + * @param aUsePlainPCB set to true to export a board with no copper or silkscreen; * this is useful for generating a VRML file which can be * converted to a STEP model. - * @param a3D_Subdir = sub directory where 3D shapes files are copied. This is only used - * when aExport3DFiles == true - * @param aXRef = X value of PCB (0,0) reference point - * @param aYRef = Y value of PCB (0,0) reference point + * @param a3D_Subdir sub directory where 3D shapes files are copied. This is only used + * when aExport3DFiles == true. + * @param aXRef X value of PCB (0,0) reference point. + * @param aYRef Y value of PCB (0,0) reference point. * @return true if Ok. */ - bool ExportVRML_File( const wxString & aFullFileName, double aMMtoWRMLunit, + bool ExportVRML_File( const wxString& aFullFileName, double aMMtoWRMLunit, bool aExport3DFiles, bool aUseRelativePaths, bool aUsePlainPCB, - const wxString & a3D_Subdir, double aXRef, double aYRef ); + const wxString& a3D_Subdir, double aXRef, double aYRef ); /** - * Function OnExportIDF3 - * will export the current BOARD to a IDFv3 board and lib files. + * Will export the current BOARD to a IDFv3 board and lib files. */ void OnExportIDF3( wxCommandEvent& event ); /** - * Function OnExportHyperlynx - * will export the current BOARD to a Hyperlynx HYP file. + * Will export the current BOARD to a Hyperlynx HYP file. */ void OnExportHyperlynx( wxCommandEvent& event ); /** - * Function Export_IDF3 * Creates an IDF3 compliant BOARD (*.emn) and LIBRARY (*.emp) file. * - * @param aPcb = a pointer to the board to be exported to IDF - * @param aFullFileName = the full filename of the export file - * @param aUseThou = set to true if the desired IDF unit is thou (mil) - * @param aXRef = the board Reference Point in mm, X value - * @param aYRef = the board Reference Point in mm, Y value - * @return true if OK + * @param aPcb a pointer to the board to be exported to IDF. + * @param aFullFileName the full filename of the export file. + * @param aUseThou set to true if the desired IDF unit is thou (mil). + * @param aXRef the board Reference Point in mm, X value. + * @param aYRef the board Reference Point in mm, Y value. + * @return true if OK. */ bool Export_IDF3( BOARD* aPcb, const wxString& aFullFileName, bool aUseThou, double aXRef, double aYRef ); /** - * Function OnExportSTEP - * Exports the current BOARD to a STEP assembly. + * Export the current BOARD to a STEP assembly. */ void OnExportSTEP( wxCommandEvent& event ); /** - * Function ExportSpecctraFile - * will export the current BOARD to a specctra dsn file. - * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the - * specification. + * Export the current BOARD to a specctra dsn file. + * + * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the specification. + * * @return true if OK */ bool ExportSpecctraFile( const wxString& aFullFilename ); /** - * Function ImportSpecctraSession - * will import a specctra *.ses file and use it to relocate MODULEs and - * to replace all vias and tracks in an existing and loaded BOARD. - * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the - * specification. + * Import a specctra *.ses file and use it to relocate MODULEs and to replace all vias and + * tracks in an existing and loaded #BOARD. + * + * See http://www.autotraxeda.com/docs/SPECCTRA/SPECCTRA.pdf for the specification. */ bool ImportSpecctraSession( const wxString& aFullFilename ); @@ -727,51 +691,48 @@ public: int ShowExchangeFootprintsDialog( FOOTPRINT* aFootprint, bool aUpdateMode, bool aSelectedMode ); /** - * Function Exchange_Module - * Replaces OldModule by NewModule, using OldModule settings: - * position, orientation, pad netnames ...) - * OldModule is deleted or put in undo list. - * @param aExisting = footprint to replace - * @param aNew = footprint to put - * @param aCommit = commit that should store the changes + * Replace \a aExisting footprint by \a aNew footprint using the \a Existing footprint + * settings (position, orientation, pad netnames ...). + * + * The \a aExisting footprint is deleted or put in undo list. + * + * @param aExisting footprint to replace. + * @param aNew footprint to put. + * @param aCommit commit that should store the changes. */ void ExchangeFootprint( FOOTPRINT* aExisting, FOOTPRINT* aNew, BOARD_COMMIT& aCommit, bool deleteExtraTexts = true, bool resetTextLayers = true, bool resetTextEffects = true, bool resetFabricationAttrs = true, bool reset3DModels = true ); - // loading footprints: see PCB_BASE_FRAME - /** - * Function OnEditItemRequest - * Install the corresponding dialog editor for the given item - * @param aDC = the current device context - * @param aItem = a pointer to the BOARD_ITEM to edit + * Install the corresponding dialog editor for the given item. + * + * @param aDC the current device context. + * @param aItem a pointer to the BOARD_ITEM to edit. */ void OnEditItemRequest( BOARD_ITEM* aItem ) override; void SwitchLayer( wxDC* DC, PCB_LAYER_ID layer ) override; /** - * Function SetTrackSegmentWidth - * Modify one track segment width or one via diameter (using DRC control). - * Basic routine used by other routines when editing tracks or vias. - * Note that casting this to boolean will allow you to determine whether any action - * happened. - * @param aTrackItem = the track segment or via to modify - * @param aItemsListPicker = the list picker to use for an undo command - * (can be NULL) - * @param aUseNetclassValue = true to use NetClass value, false to use - * current designSettings value + * Modify one track segment width or one via diameter (using DRC control). + * + * Basic routine used by other routines when editing tracks or vias. + * Note that casting this to boolean will allow you to determine whether any action + * happened. + * + * @param aTrackItem the track segment or via to modify. + * @param aItemsListPicker the list picker to use for an undo command (can be NULL). + * @param aUseNetclassValue true to use NetClass value, false to use current designSettings + * value. */ - void SetTrackSegmentWidth( TRACK* aTrackItem, - PICKED_ITEMS_LIST* aItemsListPicker, - bool aUseNetclassValue ); + void SetTrackSegmentWidth( TRACK* aTrackItem, PICKED_ITEMS_LIST* aItemsListPicker, + bool aUseNetclassValue ); /** - * Function Edit_Zone_Params - * Edit params (layer, clearance, ...) for a zone outline + * Edit params (layer, clearance, ...) for a zone outline. */ void Edit_Zone_Params( ZONE* zone_container ); @@ -781,93 +742,87 @@ public: void InstallNetlistFrame(); /** - * Function FetchNetlistFromSchematic - * @param aNetlist a NETLIST owned by the caller. This function fills it in. + * @param aNetlist a #NETLIST owned by the caller. This function fills it in. * @return true if a netlist was fetched. */ enum FETCH_NETLIST_MODE { NO_ANNOTATION, QUIET_ANNOTATION, ANNOTATION_DIALOG }; bool FetchNetlistFromSchematic( NETLIST& aNetlist, FETCH_NETLIST_MODE aMode ); /** - * Sends a command to Eeschema to re-annotate the schematic - * @param aNetlist a NETLIST filled in by the caller. - * aMessage is the error message from eeSchem - * if aCommit is false it just test, if true it updates the schematic + * Send a command to Eeschema to re-annotate the schematic. + * + * @param aNetlist a #NETLIST filled in by the caller. * @return false if failed due to standalone mode, true if a reply. */ bool ReannotateSchematic( std::string& aNetlist ); /** * Test if standalone mode. - * @return true if in standalone, opens eeSchema, and opens the schematic for this project + * + * @return true if in standalone, opens Eeschema, and opens the schematic for this project */ bool TestStandalone( void ); /** - * Function DoUpdatePCBFromNetlist * An automated version of UpdatePCBFromNetlist which skips the UI dialog. - * @param aNetlist - * @param aUseTimestamps */ void DoUpdatePCBFromNetlist( NETLIST& aNetlist, bool aUseTimestamps ); /** - * Reads a netlist from a file into a NETLIST object. + * Read a netlist from a file into a #NETLIST object. * - * @param aFilename is the netlist to load - * @param aNetlist is the object to populate with data - * @param aReporter is a #REPORTER object to display messages - * @return true if the netlist was read successfully + * @param aFilename is the netlist to load. + * @param aNetlist is the object to populate with data. + * @param aReporter is a #REPORTER object to display messages. + * @return true if the netlist was read successfully. */ bool ReadNetlistFromFile( const wxString &aFilename, NETLIST& aNetlist, REPORTER& aReporter ); /** - * Called after netlist is updated - * @param aUpdater is the updater object that was run - * @param aRunDragCommand is set to true if the drag command was invoked by this call + * Called after netlist is updated. + * + * @param aUpdater is the updater object that was run. + * @param aRunDragCommand is set to true if the drag command was invoked by this call. */ void OnNetlistChanged( BOARD_NETLIST_UPDATER& aUpdater, bool* aRunDragCommand ); #if defined( KICAD_SCRIPTING_WXPYTHON ) /** - * Function ScriptingConsoleEnableDisable - * enables or disabled the scripting console + * Enable or disable the scripting console. */ void ScriptingConsoleEnableDisable(); #endif /** - * Function SendMessageToEESCHEMA - * sends a message to the schematic editor so that it may move its cursor - * to a part with the same reference as the objectToSync + * Send a message to the schematic editor so that it may move its cursor + * to a symbol with the same reference as the \a objectToSync. + * * @param objectToSync The object whose reference is used to synchronize Eeschema. */ void SendMessageToEESCHEMA( BOARD_ITEM* objectToSync ); /** - * Sends a net name to eeschema for highlighting + * Send a net name to Eeschema for highlighting. * - * @param aNetName is the name of a net, or empty string to clear highlight + * @param aNetName is the name of a net, or empty string to clear highlight. */ void SendCrossProbeNetName( const wxString& aNetName ); void ShowChangedLanguage() override; /** - * Function UpdateTitle - * sets the main window title bar text. - *

+ * Set the main window title bar text. + * * If file name defined by PCB_SCREEN::m_FileName is not set, the title is set to the * application name appended with no file. Otherwise, the title is set to the full path * and file name and read only is appended to the title if the user does not have write * access to the file. - *

*/ void UpdateTitle(); /** - * Allows Pcbnew to install its preferences panel into the preferences dialog. + * Allow Pcbnew to install its preferences panel into the preferences dialog. */ void InstallPreferences( PAGED_DIALOG* aParent, PANEL_HOTKEYS_EDITOR* aHotkeysPanel ) override; diff --git a/pcbnew/pcb_painter.h b/pcbnew/pcb_painter.h index a1f4910849..20059f48c2 100644 --- a/pcbnew/pcb_painter.h +++ b/pcbnew/pcb_painter.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN - * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -58,15 +59,14 @@ namespace KIGFX class GAL; /** - * PCB_RENDER_SETTINGS - * Stores PCB specific render settings. + * PCB specific render settings. */ class PCB_RENDER_SETTINGS : public RENDER_SETTINGS { public: friend class PCB_PAINTER; - ///> Flags to control clearance lines visibility + ///< Flags to control clearance lines visibility enum CLEARANCE_MODE { CL_NONE = 0x00, @@ -85,9 +85,9 @@ public: PCB_RENDER_SETTINGS(); /** - * Function LoadDisplayOptions - * Loads settings related to display options (high-contrast mode, full or outline modes + * Load settings related to display options (high-contrast mode, full or outline modes * for vias/pads/tracks and so on). + * * @param aOptions are settings that you want to use for displaying items. */ void LoadDisplayOptions( const PCB_DISPLAY_OPTIONS& aOptions, bool aShowPageLimits ); @@ -98,11 +98,11 @@ public: virtual COLOR4D GetColor( const VIEW_ITEM* aItem, int aLayer ) const override; /** - * Function SetSketchMode - * Turns on/off sketch mode for given item layer. + * Turn on/off sketch mode for given item layer. + * * @param aItemLayer is the item layer that is changed. * @param aEnabled decides if it is drawn in sketch mode (true for sketched mode, - * false for filled mode). + * false for filled mode). */ inline void SetSketchMode( int aItemLayer, bool aEnabled ) { @@ -110,8 +110,8 @@ public: } /** - * Function GetSketchMode - * Returns sketch mode setting for a given item layer. + * Return sketch mode setting for a given item layer. + * * @param aItemLayer is the item layer that is changed. */ inline bool GetSketchMode( int aItemLayer ) const @@ -120,9 +120,10 @@ public: } /** - * Turns on/off sketch mode for graphic items (DRAWSEGMENTs, texts). + * Turn on/off sketch mode for graphic items (DRAWSEGMENTs, texts). + * * @param aEnabled decides if it is drawn in sketch mode (true for sketched mode, - * false for filled mode). + * false for filled mode). */ inline void SetSketchModeGraphicItems( bool aEnabled ) { @@ -130,7 +131,7 @@ public: } /** - * Turns on/off drawing outline and hatched lines for zones. + * Turn on/off drawing outline and hatched lines for zones. */ void EnableZoneOutlines( bool aEnabled ) { @@ -155,12 +156,14 @@ public: const COLOR4D& GetCursorColor() override { return m_layerColors[ LAYER_CURSOR ]; } - /** Switch the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN ) + /** + * Switch the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN ) * to control how the non active layers are shown */ void SetContrastModeDisplay( HIGH_CONTRAST_MODE aMode ) { m_contrastModeDisplay = aMode; } - /** return the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN ) + /** + * @return the contrast mode setting (HIGH_CONTRAST_MODE:NORMAL, DIMMED or HIDDEN ). */ HIGH_CONTRAST_MODE GetContrastModeDisplay() { return m_contrastModeDisplay; } @@ -187,7 +190,7 @@ public: void SetZoneDisplayMode( ZONE_DISPLAY_MODE mode ) { m_zoneDisplayMode = mode; } protected: - ///> Maximum font size for netnames (and other dynamically shown strings) + ///< Maximum font size for netnames (and other dynamically shown strings) static const double MAX_FONT_SIZE; bool m_sketchMode[GAL_LAYER_ID_END]; @@ -212,16 +215,16 @@ protected: int m_clearanceDisplayFlags; - ///> How to display nets and netclasses with color overrides + ///< How to display nets and netclasses with color overrides NET_COLOR_MODE m_netColorMode; - ///> Overrides for specific netclass colors + ///< Overrides for specific netclass colors std::map m_netclassColors; - ///> Overrides for specific net colors, stored as netcodes for the ratsnest to access easily + ///< Overrides for specific net colors, stored as netcodes for the ratsnest to access easily std::map m_netColors; - ///> Set of net codes that should not have their ratsnest displayed + ///< Set of net codes that should not have their ratsnest displayed std::set m_hiddenNets; // These opacity overrides multiply with any opacity in the base layer color @@ -233,7 +236,6 @@ protected: /** - * PCB_PAINTER * Contains methods for drawing PCB-specific items. */ class PCB_PAINTER : public PAINTER @@ -273,9 +275,8 @@ protected: void draw( const PCB_MARKER* aMarker, int aLayer ); /** - * Function getLineThickness() - * Get the thickness to draw for a line (e.g. 0 thickness lines - * get a minimum value). + * Get the thickness to draw for a line (e.g. 0 thickness lines get a minimum value). + * * @param aActualThickness line own thickness * @return the thickness to draw */ diff --git a/pcbnew/pcbnew_printout.h b/pcbnew/pcbnew_printout.h index 3b14a626aa..ac614a6af3 100644 --- a/pcbnew/pcbnew_printout.h +++ b/pcbnew/pcbnew_printout.h @@ -1,7 +1,8 @@ /* - * Copyright (C) 1992-2016 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2018 CERN - * Author: Maciej Suminski + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. + * + * @author Maciej Suminski * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -77,9 +78,9 @@ private: namespace KIGFX { + /** - * Special flavor of PCB_PAINTER that contains - * modifications to handle printing options. + * Special flavor of PCB_PAINTER that contains modifications to handle printing options. */ class PCB_PRINT_PAINTER : public PCB_PAINTER { @@ -88,8 +89,9 @@ public: /** * Set drill marks visibility and options. + * * @param aRealSize when enabled, drill marks represent actual holes. Otherwise aSize - * parameter is used. + * parameter is used. * @param aSize is drill mark size (internal units), valid only when aRealSize == false. */ void SetDrillMarks( bool aRealSize, unsigned int aSize = 0 ) @@ -105,10 +107,10 @@ protected: int getDrillSize( const VIA* aVia ) const override; - ///> Flag deciding whether use the actual hole size or user-specified size for drill marks + ///< Flag deciding whether use the actual hole size or user-specified size for drill marks bool m_drillMarkReal; - ///> User-specified size for drill marks (expressed in internal units) + ///< User-specified size for drill marks (expressed in internal units) int m_drillMarkSize; }; diff --git a/pcbnew/plugins/eagle/eagle_plugin.h b/pcbnew/plugins/eagle/eagle_plugin.h index 3068fa905d..906d0e1517 100644 --- a/pcbnew/plugins/eagle/eagle_plugin.h +++ b/pcbnew/plugins/eagle/eagle_plugin.h @@ -5,7 +5,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2012-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -47,6 +47,38 @@ typedef NET_MAP::const_iterator NET_MAP_CITER; /// subset of eagle.drawing.board.designrules in the XML document struct ERULES { + ERULES() : + psElongationLong ( 100 ), + psElongationOffset ( 0 ), + + mvStopFrame ( 1.0 ), + mvCreamFrame ( 0.0 ), + mlMinStopFrame ( Mils2iu( 4.0 ) ), + mlMaxStopFrame ( Mils2iu( 4.0 ) ), + mlMinCreamFrame ( Mils2iu( 0.0 ) ), + mlMaxCreamFrame ( Mils2iu( 0.0 ) ), + + psTop ( EPAD::UNDEF ), + psBottom ( EPAD::UNDEF ), + psFirst ( EPAD::UNDEF ), + + srRoundness ( 0.0 ), + srMinRoundness ( Mils2iu( 0.0 ) ), + srMaxRoundness ( Mils2iu( 0.0 ) ), + + rvPadTop ( 0.25 ), + // rvPadBottom ( 0.25 ), + rlMinPadTop ( Mils2iu( 10 ) ), + rlMaxPadTop ( Mils2iu( 20 ) ), + + rvViaOuter ( 0.25 ), + rlMinViaOuter ( Mils2iu( 10 ) ), + rlMaxViaOuter ( Mils2iu( 20 ) ), + mdWireWire ( 0 ) + {} + + void parse( wxXmlNode* aRules ); + ///< percent over 100%. 0-> not elongated, 100->twice as wide as is tall ///< Goes into making a scaling factor for "long" pads. int psElongationLong; @@ -85,39 +117,6 @@ struct ERULES double rlMinViaOuter; ///< minimum copper annulus on via double rlMaxViaOuter; ///< maximum copper annulus on via double mdWireWire; ///< wire to wire spacing I presume. - - - ERULES() : - psElongationLong ( 100 ), - psElongationOffset ( 0 ), - - mvStopFrame ( 1.0 ), - mvCreamFrame ( 0.0 ), - mlMinStopFrame ( Mils2iu( 4.0 ) ), - mlMaxStopFrame ( Mils2iu( 4.0 ) ), - mlMinCreamFrame ( Mils2iu( 0.0 ) ), - mlMaxCreamFrame ( Mils2iu( 0.0 ) ), - - psTop ( EPAD::UNDEF ), - psBottom ( EPAD::UNDEF ), - psFirst ( EPAD::UNDEF ), - - srRoundness ( 0.0 ), - srMinRoundness ( Mils2iu( 0.0 ) ), - srMaxRoundness ( Mils2iu( 0.0 ) ), - - rvPadTop ( 0.25 ), - // rvPadBottom ( 0.25 ), - rlMinPadTop ( Mils2iu( 10 ) ), - rlMaxPadTop ( Mils2iu( 20 ) ), - - rvViaOuter ( 0.25 ), - rlMinViaOuter ( Mils2iu( 10 ) ), - rlMaxViaOuter ( Mils2iu( 20 ) ), - mdWireWire ( 0 ) - {} - - void parse( wxXmlNode* aRules ); }; @@ -172,38 +171,6 @@ public: const std::vector& aInputLayerDescriptionVector ); private: - typedef std::vector ELAYERS; - typedef ELAYERS::const_iterator EITER; - - int m_cu_map[17]; ///< map eagle to KiCad, cu layers only. - std::map m_eagleLayers; ///< Eagle layer data stored by layer number - std::map m_eagleLayersIds; ///< Eagle layer ids stored by layer name - std::map m_layer_map; ///< Map of Eagle layers to KiCad layers - - ERULES* m_rules; ///< Eagle design rules. - XPATH* m_xpath; ///< keeps track of what we are working on within - ///< XML document during a Load(). - - int m_hole_count; ///< generates unique footprint names from eagle "hole"s. - - NET_MAP m_pads_to_nets; ///< net list - - FOOTPRINT_MAP m_templates; ///< is part of a FOOTPRINT factory that operates using copy - ///< construction. - ///< lookup key is either libname.packagename or simply - ///< packagename if FootprintLoad() or FootprintEnumberate() - - const PROPERTIES* m_props; ///< passed via Save() or Load(), no ownership, may be NULL. - BOARD* m_board; ///< which BOARD is being worked on, no ownership here - - int m_min_trace; ///< smallest trace we find on Load(), in BIU. - int m_min_hole; ///< smallest diameter hole we find on Load(), in BIU. - int m_min_via; ///< smallest via we find on Load(), in BIU. - int m_min_annulus; ///< smallest via annulus we find on Load(), in BIU. - - wxString m_lib_path; - wxDateTime m_mod_time; - /// initialize PLUGIN like a constructor would, and futz with fresh BOARD if needed. void init( const PROPERTIES* aProperties ); @@ -216,13 +183,13 @@ private: /// create a font size (fontz) from an eagle font size scalar and KiCad font thickness wxSize kicad_fontz( const ECOORD& d, int aTextThickness ) const; - /// Generate mapping between Eagle na KiCAD layers + /// Generate mapping between Eagle na KiCad layers void mapEagleLayersToKicad(); /// Convert an Eagle layer to a KiCad layer. PCB_LAYER_ID kicad_layer( int aLayer ) const; - /// Get default KiCAD layer corresponding to an Eagle layer of the board, + /// Get default KiCad layer corresponding to an Eagle layer of the board, /// a set of sensible layer mapping options and required flag std::tuple defaultKicadLayer( int aEagleLayer ) const; @@ -298,11 +265,43 @@ private: void packageHole( FOOTPRINT* aFootprint, wxXmlNode* aTree, bool aCenter ) const; void packageSMD( FOOTPRINT* aFootprint, wxXmlNode* aTree ) const; - ///> Handles common pad properties + ///< Handles common pad properties void transferPad( const EPAD_COMMON& aEaglePad, PAD* aPad ) const; - ///> Deletes the footprint templates list + ///< Deletes the footprint templates list void deleteTemplates(); + + typedef std::vector ELAYERS; + typedef ELAYERS::const_iterator EITER; + + int m_cu_map[17]; ///< map eagle to KiCad, cu layers only. + std::map m_eagleLayers; ///< Eagle layer data stored by layer number + std::map m_eagleLayersIds; ///< Eagle layer ids stored by layer name + std::map m_layer_map; ///< Map of Eagle layers to KiCad layers + + ERULES* m_rules; ///< Eagle design rules. + XPATH* m_xpath; ///< keeps track of what we are working on within + ///< XML document during a Load(). + + int m_hole_count; ///< generates unique footprint names from eagle "hole"s. + + NET_MAP m_pads_to_nets; ///< net list + + FOOTPRINT_MAP m_templates; ///< is part of a FOOTPRINT factory that operates using copy + ///< construction. + ///< lookup key is either libname.packagename or simply + ///< packagename if FootprintLoad() or FootprintEnumberate() + + const PROPERTIES* m_props; ///< passed via Save() or Load(), no ownership, may be NULL. + BOARD* m_board; ///< which BOARD is being worked on, no ownership here + + int m_min_trace; ///< smallest trace we find on Load(), in BIU. + int m_min_hole; ///< smallest diameter hole we find on Load(), in BIU. + int m_min_via; ///< smallest via we find on Load(), in BIU. + int m_min_annulus; ///< smallest via annulus we find on Load(), in BIU. + + wxString m_lib_path; + wxDateTime m_mod_time; }; #endif // EAGLE_PLUGIN_H_ diff --git a/pcbnew/plugins/kicad/pcb_parser.h b/pcbnew/plugins/kicad/pcb_parser.h index e4aec0399e..6c2af11e64 100644 --- a/pcbnew/plugins/kicad/pcb_parser.h +++ b/pcbnew/plugins/kicad/pcb_parser.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 CERN - * Copyright (C) 2012-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2012-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -62,44 +62,71 @@ struct LAYER; /** - * PCB_PARSER - * reads a Pcbnew s-expression formatted #LINE_READER object and returns the appropriate + * Read a Pcbnew s-expression formatted #LINE_READER object and returns the appropriate * #BOARD_ITEM object. */ class PCB_PARSER : public PCB_LEXER { - typedef std::unordered_map< std::string, PCB_LAYER_ID > LAYER_ID_MAP; - typedef std::unordered_map< std::string, LSET > LSET_MAP; - typedef std::unordered_map< wxString, KIID > KIID_MAP; - - BOARD* m_board; - LAYER_ID_MAP m_layerIndices; ///< map layer name to it's index - LSET_MAP m_layerMasks; ///< map layer names to their masks - std::set m_undefinedLayers; ///< set of layers not defined in layers section - std::vector m_netCodes; ///< net codes mapping for boards being loaded - bool m_tooRecent; ///< true if version parses as later than supported - int m_requiredVersion; ///< set to the KiCad format version this board requires - bool m_resetKIIDs; ///< reading into an existing board; reset UUIDs - KIID_MAP m_resetKIIDMap; ///< if resetting UUIDs, record new ones to update groups with - - bool m_showLegacyZoneWarning; - - // Group membership info refers to other Uuids in the file. - // We don't want to rely on group declarations being last in the file, so - // we store info about the group declarations here during parsing and then resolve - // them into BOARD_ITEM* after we've parsed the rest of the file. - typedef struct +public: + PCB_PARSER( LINE_READER* aReader = NULL ) : + PCB_LEXER( aReader ), + m_board( nullptr ), + m_resetKIIDs( false ) { - BOARD_ITEM* parent; - wxString name; - KIID uuid; - std::vector memberUuids; - } GROUP_INFO; + init(); + } - std::vector m_groupInfos; + // ~PCB_PARSER() {} - ///> Converts net code using the mapping table if available, - ///> otherwise returns unchanged net code if < 0 or if is is out of range + /** + * Set @a aLineReader into the parser, and returns the previous one, if any. + * + * @param aReader is what to read from for tokens, no ownership is received. + * @return LINE_READER* - previous LINE_READER or NULL if none. + */ + LINE_READER* SetLineReader( LINE_READER* aReader ) + { + LINE_READER* ret = PopReader(); + PushReader( aReader ); + return ret; + } + + void SetBoard( BOARD* aBoard ) + { + init(); + m_board = aBoard; + + if( aBoard != nullptr ) + m_resetKIIDs = true; + } + + BOARD_ITEM* Parse(); + + /** + * @param aInitialComments may be a pointer to a heap allocated initial comment block + * or NULL. If not NULL, then caller has given ownership of a + * wxArrayString to this function and care must be taken to + * delete it even on exception. + */ + FOOTPRINT* parseFOOTPRINT( wxArrayString* aInitialComments = 0 ); + + /** + * Return whether a version number, if any was parsed, was too recent + */ + bool IsTooRecent() + { + return m_tooRecent; + } + + /** + * Return a string representing the version of KiCad required to open this + * file. Not particularly meaningful if IsTooRecent() returns false. + */ + wxString GetRequiredVersion(); + +private: + ///< Convert net code using the mapping table if available, + ///< otherwise returns unchanged net code if < 0 or if is is out of range inline int getNetCode( int aNetCode ) { if( ( aNetCode >= 0 ) && ( aNetCode < (int) m_netCodes.size() ) ) @@ -109,34 +136,35 @@ class PCB_PARSER : public PCB_LEXER } /** - * function pushValueIntoMap - * Add aValue value in netcode mapping (m_netCodes) at index aIndex - * ensure there is room in m_netCodes for that, and add room if needed. - * @param aIndex = the index ( expected >=0 )of the location to use in m_netCodes - * @param aValue = the netcode value to map + * Add aValue value in netcode mapping (m_netCodes) at \a aIndex. + * + * Ensure there is room in m_netCodes for that, and add room if needed. + * + * @param aIndex is the index ( expected >=0 )of the location to use in m_netCodes. + * @param aValue is the netcode value to map. */ void pushValueIntoMap( int aIndex, int aValue ); /** - * Function init - * clears and re-establishes m_layerMap with the default layer names. + * Clear and re-establish m_layerMap with the default layer names. + * * m_layerMap will have some of its entries overwritten whenever a (new) board * is encountered. */ void init(); /** - * Creates a mapping from the (short-lived) bug where layer names were translated - * TODO: Remove this once we support custom layer names + * Create a mapping from the (short-lived) bug where layer names were translated. * - * @param aMap string mapping from translated to English layer names + * @todo Remove this once we support custom layer names. + * + * @param aMap string mapping from translated to English layer names. */ void createOldLayerMapping( std::unordered_map< std::string, std::string >& aMap ); /** - * Function skipCurrent - * Skip the current token level, i.e - * search for the RIGHT parenthesis which closes the current description + * Skip the current token level, i.e search for the RIGHT parenthesis which closes the + * current description. */ void skipCurrent(); @@ -182,48 +210,43 @@ class PCB_PARSER : public PCB_LEXER BOARD* parseBOARD_unchecked(); /** - * Function lookUpLayer - * parses the current token for the layer definition of a #BOARD_ITEM object. + * Parse the current token for the layer definition of a #BOARD_ITEM object. * * @param aMap is the LAYER_{NUM|MSK}_MAP to use for the lookup. - * + * @return The result of the parsed #BOARD_ITEM layer or set designator. * @throw IO_ERROR if the layer is not valid. * @throw PARSE_ERROR if the layer syntax is incorrect. - * @return int - The result of the parsed #BOARD_ITEM layer or set designator. */ template T lookUpLayer( const M& aMap ); /** - * Function parseBoardItemLayer - * parses the layer definition of a #BOARD_ITEM object. + * Parse the layer definition of a #BOARD_ITEM object. * + * @return The index the parsed #BOARD_ITEM layer. * @throw IO_ERROR if the layer is not valid. * @throw PARSE_ERROR if the layer syntax is incorrect. - * @return The index the parsed #BOARD_ITEM layer. */ PCB_LAYER_ID parseBoardItemLayer(); /** - * Function parseBoardItemLayersAsMask - * parses the layers definition of a #BOARD_ITEM object. + * Parse the layers definition of a #BOARD_ITEM object. * + * @return The mask of layers the parsed #BOARD_ITEM is on. * @throw IO_ERROR if any of the layers is not valid. * @throw PARSE_ERROR if the layers syntax is incorrect. - * @return The mask of layers the parsed #BOARD_ITEM is on. */ LSET parseBoardItemLayersAsMask(); /** - * Function parseXY - * parses a coordinate pair (xy X Y) in board units (mm). + * Parse a coordinate pair (xy X Y) in board units (mm). * * The parser checks if the previous token was T_LEFT and parses the remainder of * the token syntax. This is used when parsing a list of coordinate points. This * way the parser can be used in either case. * - * @throw PARSE_ERROR if the coordinate pair syntax is incorrect. * @return A wxPoint object containing the coordinate pair. + * @throw PARSE_ERROR if the coordinate pair syntax is incorrect. */ wxPoint parseXY(); @@ -232,23 +255,21 @@ class PCB_PARSER : public PCB_LEXER std::pair parseProperty(); /** - * Function parseEDA_TEXT - * parses the common settings for any object derived from #EDA_TEXT. + * Parse the common settings for any object derived from #EDA_TEXT. * - * @throw PARSE_ERROR if the text syntax is not valid. * @param aText A point to the #EDA_TEXT object to save the parsed settings into. + * @throw PARSE_ERROR if the text syntax is not valid. */ void parseEDA_TEXT( EDA_TEXT* aText ); FP_3DMODEL* parse3DModel(); /** - * Function parseDouble - * parses the current token as an ASCII numeric string with possible leading + * Parse the current token as an ASCII numeric string with possible leading * whitespace into a double precision floating point number. * - * @throw IO_ERROR if an error occurs attempting to convert the current token. * @return The result of the parsed token. + * @throw IO_ERROR if an error occurs attempting to convert the current token. */ double parseDouble(); @@ -277,7 +298,7 @@ class PCB_PARSER : public PCB_LEXER // larger or smaller than those board units represent undefined behavior for // the system. We limit values to the largest that is visible on the screen // This is the diagonal distance of the full screen ~1.5m - double int_limit = std::numeric_limits::max() * 0.7071; // 0.7071 = roughly 1/sqrt(2) + double int_limit = std::numeric_limits::max() * 0.7071; // 0.7071 = roughly 1/sqrt(2) return KiROUND( Clamp( -int_limit, retval, int_limit ) ); } @@ -290,9 +311,8 @@ class PCB_PARSER : public PCB_LEXER // the system. We limit values to the largest that is visible on the screen double int_limit = std::numeric_limits::max() * 0.7071; - // Use here KiROUND, not KIROUND (see comments about them) - // when having a function as argument, because it will be called twice - // with KIROUND + // Use here #KiROUND, not EKIROUND (see comments about them) when having a function as + // argument, because it will be called twice with #KIROUND. return KiROUND( Clamp( -int_limit, retval, int_limit ) ); } @@ -321,7 +341,7 @@ class PCB_PARSER : public PCB_LEXER bool parseBool(); /* - * @return if m_resetKIIDs, returns new KIID(), otehrwise returns CurStr() as KIID. + * @return if m_resetKIIDs, returns new KIID(), otherwise returns CurStr() as KIID. */ KIID CurStrToKIID(); @@ -331,63 +351,37 @@ class PCB_PARSER : public PCB_LEXER */ void resolveGroups( BOARD_ITEM* aParent ); -public: + typedef std::unordered_map< std::string, PCB_LAYER_ID > LAYER_ID_MAP; + typedef std::unordered_map< std::string, LSET > LSET_MAP; + typedef std::unordered_map< wxString, KIID > KIID_MAP; - PCB_PARSER( LINE_READER* aReader = NULL ) : - PCB_LEXER( aReader ), - m_board( nullptr ), - m_resetKIIDs( false ) + BOARD* m_board; + LAYER_ID_MAP m_layerIndices; ///< map layer name to it's index + LSET_MAP m_layerMasks; ///< map layer names to their masks + std::set m_undefinedLayers; ///< set of layers not defined in layers section + std::vector m_netCodes; ///< net codes mapping for boards being loaded + bool m_tooRecent; ///< true if version parses as later than supported + int m_requiredVersion; ///< set to the KiCad format version this board requires + bool m_resetKIIDs; ///< reading into an existing board; reset UUIDs + + ///< if resetting UUIDs, record new ones to update groups with. + KIID_MAP m_resetKIIDMap; + + bool m_showLegacyZoneWarning; + + // Group membership info refers to other Uuids in the file. + // We don't want to rely on group declarations being last in the file, so + // we store info about the group declarations here during parsing and then resolve + // them into BOARD_ITEM* after we've parsed the rest of the file. + typedef struct { - init(); - } - - // ~PCB_PARSER() {} - - /** - * Function SetLineReader - * sets @a aLineReader into the parser, and returns the previous one, if any. - * @param aReader is what to read from for tokens, no ownership is received. - * @return LINE_READER* - previous LINE_READER or NULL if none. - */ - LINE_READER* SetLineReader( LINE_READER* aReader ) - { - LINE_READER* ret = PopReader(); - PushReader( aReader ); - return ret; - } - - void SetBoard( BOARD* aBoard ) - { - init(); - m_board = aBoard; - - if( aBoard != nullptr ) - m_resetKIIDs = true; - } - - BOARD_ITEM* Parse(); - /** - * Function parseFOOTPRINT - * @param aInitialComments may be a pointer to a heap allocated initial comment block - * or NULL. If not NULL, then caller has given ownership of a wxArrayString to - * this function and care must be taken to delete it even on exception. - */ - FOOTPRINT* parseFOOTPRINT( wxArrayString* aInitialComments = 0 ); - - /** - * Return whether a version number, if any was parsed, was too recent - */ - bool IsTooRecent() - { - return m_tooRecent; - } - - /** - * Return a string representing the version of kicad required to open this - * file. Not particularly meaningful if IsTooRecent() returns false. - */ - wxString GetRequiredVersion(); + BOARD_ITEM* parent; + wxString name; + KIID uuid; + std::vector memberUuids; + } GROUP_INFO; + std::vector m_groupInfos; }; diff --git a/pcbnew/plugins/legacy/legacy_plugin.h b/pcbnew/plugins/legacy/legacy_plugin.h index 7aaf05f0be..36024e9d2a 100644 --- a/pcbnew/plugins/legacy/legacy_plugin.h +++ b/pcbnew/plugins/legacy/legacy_plugin.h @@ -5,7 +5,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -55,6 +55,7 @@ struct LP_CACHE; /** * A #PLUGIN derivation which could possibly be put into a DLL/DSO. + * * As with any PLUGIN, there is no UI, i.e. windowing calls allowed. */ class LEGACY_PLUGIN : public PLUGIN @@ -101,8 +102,8 @@ public: static LSET leg_mask2new( int cu_count, unsigned aMask ); protected: - ///> Converts net code using the mapping table if available, - ///> otherwise returns unchanged net code + ///< Converts net code using the mapping table if available, + ///< otherwise returns unchanged net code inline int getNetCode( int aNetCode ) { if( (unsigned int) aNetCode < m_netCodes.size() ) @@ -115,7 +116,7 @@ protected: * Parse an ASCII decimal floating point value and scales it into a BIU according to the * current value of diskToBui. * - * This fuction is the complement of #fmtBIU(). One has to know what the other is doing. + * This function is the complement of #fmtBIU(). One has to know what the other is doing. * * @param aValue is the ASCII value in C locale form with possible leading whitespace * @param nptrptr may be NULL, but if not, then it tells where to put a pointer to the diff --git a/pcbnew/ratsnest/ratsnest_data.h b/pcbnew/ratsnest/ratsnest_data.h index 38eacfed2b..97d3823dfc 100644 --- a/pcbnew/ratsnest/ratsnest_data.h +++ b/pcbnew/ratsnest/ratsnest_data.h @@ -2,7 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2013-2015 CERN - * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -55,26 +56,23 @@ struct CN_PTR_CMP }; /** - * RN_NET - * Describes ratsnest for a single net. + * Describe ratsnest for a single net. */ class RN_NET { public: - ///> Default constructor. RN_NET(); /** - * Function SetVisible() - * Sets state of the visibility flag. + * Set state of the visibility flag. + * * @param aEnabled is new state. True if ratsnest for a given net is meant to be displayed, - * false otherwise. + * false otherwise. */ void SetVisible( bool aEnabled ); /** - * Function MarkDirty() - * Marks ratsnest for given net as 'dirty', i.e. requiring recomputation. + * Mark ratsnest for given net as 'dirty', i.e. requiring recomputation. */ void MarkDirty() { @@ -82,9 +80,9 @@ public: } /** - * Function IsDirty() - * Returns state of the 'dirty' flag, indicating that ratsnest for a given net is invalid + * Return state of the 'dirty' flag, indicating that ratsnest for a given net is invalid * and requires an update. + * * @return True if ratsnest requires recomputation, false otherwise. */ bool IsDirty() const @@ -93,8 +91,8 @@ public: } /** - * Function GetUnconnected() - * Returns pointer to a vector of edges that makes ratsnest for a given net. + * Return pointer to a vector of edges that makes ratsnest for a given net. + * * @return Pointer to a vector of edges that makes ratsnest for a given net. */ const std::vector GetUnconnected() const @@ -103,8 +101,7 @@ public: } /** - * Function Update() - * Recomputes ratsnest for a net. + * Recompute ratsnest for a net. */ void Update(); void Clear(); @@ -117,8 +114,8 @@ public: } /** - * Function GetNodes() - * Returns list of nodes that are associated with a given item. + * Return list of nodes that are associated with a given item. + * * @param aItem is an item for which the list is generated. * @return List of associated nodes. */ @@ -130,39 +127,40 @@ public: } /** - * Function GetAllItems() - * Adds all stored items to a list. + * Add all stored items to a list. + * * @param aOutput is the list that will have items added. * @param aTypes determines the type of added items. */ void GetAllItems( std::list& aOutput, const KICAD_T aTypes[] ) const; /** - * Function GetClosestNode() - * Returns a single node that lies in the shortest distance from a specific node. + * Return a single node that lies in the shortest distance from a specific node. + * * @param aNode is the node for which the closest node is searched. */ const CN_ANCHOR_PTR GetClosestNode( const CN_ANCHOR_PTR& aNode ) const; - bool NearestBicoloredPair( const RN_NET& aOtherNet, CN_ANCHOR_PTR& aNode1, CN_ANCHOR_PTR& aNode2 ) const; + bool NearestBicoloredPair( const RN_NET& aOtherNet, CN_ANCHOR_PTR& aNode1, + CN_ANCHOR_PTR& aNode2 ) const; protected: - ///> Recomputes ratsnest from scratch. + ///< Recompute ratsnest from scratch. void compute(); - ///> Compute the minimum spanning tree using Kruskal's algorithm + ///< Compute the minimum spanning tree using Kruskal's algorithm void kruskalMST( const std::vector &aEdges ); - ///> Vector of nodes + ///< Vector of nodes std::multiset m_nodes; - ///> Vector of edges that make pre-defined connections + ///< Vector of edges that make pre-defined connections std::vector m_boardEdges; - ///> Vector of edges that makes ratsnest for a given net. + ///< Vector of edges that makes ratsnest for a given net. std::vector m_rnEdges; - ///> Flag indicating necessity of recalculation of ratsnest for a net. + ///< Flag indicating necessity of recalculation of ratsnest for a net. bool m_dirty; class TRIANGULATOR_STATE; diff --git a/pcbnew/ratsnest/ratsnest_viewitem.h b/pcbnew/ratsnest/ratsnest_viewitem.h index 2fb2259895..5b2c524b66 100644 --- a/pcbnew/ratsnest/ratsnest_viewitem.h +++ b/pcbnew/ratsnest/ratsnest_viewitem.h @@ -2,6 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -63,8 +65,10 @@ public: void Show( int x, std::ostream& st ) const override { } #endif - /** Get class name - * @return string "RATSNEST_VIEWITEM" + /** + * Get class name. + * + * @return string "RATSNEST_VIEWITEM" */ virtual wxString GetClass() const override { @@ -72,7 +76,7 @@ public: } protected: - ///> Object containing ratsnest data. + ///< Object containing ratsnest data. std::shared_ptr m_data; }; diff --git a/pcbnew/router/pns_algo_base.h b/pcbnew/router/pns_algo_base.h index b960a35e7c..32c01ed31e 100644 --- a/pcbnew/router/pns_algo_base.h +++ b/pcbnew/router/pns_algo_base.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -31,32 +32,32 @@ class LOGGER; class DEBUG_DECORATOR; /** - * ALGO_BASE + * Base class for all P&S algorithms (shoving, walkaround, line placement, dragging, etc.). * - * Base class for all P&S algorithms (shoving, walkaround, line placement, dragging, etc.) - * Holds a bunch of objects commonly used by all algorithms (P&S settings, parent router instance, logging) + * Holds a bunch of objects commonly used by all algorithms (P&S settings, parent router + * instance, logging). */ class ALGO_BASE { public: ALGO_BASE( ROUTER* aRouter ) : - m_debugDecorator( nullptr ), + m_debugDecorator( nullptr ), m_router( aRouter ), m_logger( nullptr ) {} virtual ~ALGO_BASE() {} - ///> Returns the instance of our router + ///< Return the instance of our router ROUTER* Router() const { return m_router; } - ///> Returns current router settings + ///< Return current router settings ROUTING_SETTINGS& Settings() const; - ///> Returns the logger object, allowing to dump geometry to a file. + ///< Return the logger object, allowing to dump geometry to a file. virtual LOGGER* Logger(); void SetLogger( LOGGER* aLogger ) @@ -65,10 +66,8 @@ public: } /** - * Function SetDebugDecorator - * - * Assign a debug decorator allowing this algo to draw extra graphics for visual debugging - */ + * Assign a debug decorator allowing this algo to draw extra graphics for visual debugging. + */ void SetDebugDecorator( DEBUG_DECORATOR* aDecorator ) { m_debugDecorator = aDecorator; diff --git a/pcbnew/router/pns_diff_pair_placer.h b/pcbnew/router/pns_diff_pair_placer.h index c4d5b5529c..8a14377ec6 100644 --- a/pcbnew/router/pns_diff_pair_placer.h +++ b/pcbnew/router/pns_diff_pair_placer.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -46,10 +47,9 @@ class SIZES_SETTINGS; /** - * LINE_PLACER + * Single track placement algorithm. * - * Single track placement algorithm. Interactively routes a track. - * Applies shove and walkaround algorithms when needed. + * Interactively routes a track and applies shove and walk around algorithms when needed. */ class DIFF_PAIR_PLACER : public PLACEMENT_ALGO @@ -62,30 +62,23 @@ public: DP_PRIMITIVE_PAIR& aPair, wxString* aErrorMsg = nullptr ); /** - * Function Start() - * - * Starts routing a single track at point aP, taking item aStartItem as anchor - * (unless NULL). + * Start routing a single track at point aP, taking item aStartItem as anchor (unless NULL). */ bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override; /** - * Function Move() - * - * Moves the end of the currently routed trace to the point aP, taking - * aEndItem as anchor (if not NULL). - * (unless NULL). + * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as + * anchor (if not NULL). */ bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override; /** - * Function FixRoute() + * Commit the currently routed track to the parent node, taking \a aP as the final end + * point and \a aEndItem as the final anchor (if provided). * - * Commits the currently routed track to the parent node, taking - * aP as the final end point and aEndItem as the final anchor (if provided). - * @return true, if route has been commited. May return false if the routing - * result is violating design rules - in such case, the track is only committed - * if Settings.CanViolateDRC() is on. + * @return true if route has been committed. May return false if the routing result is + * violating design rules. In such cases, the track is only committed if + * #Settings.CanViolateDRC() is on. */ bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish ) override; @@ -99,31 +92,23 @@ public: bool HasPlacedAnything() const override; /** - * Function ToggleVia() - * - * Enables/disables a via at the end of currently routed trace. + * Enable/disable a via at the end of currently routed trace. */ bool ToggleVia( bool aEnabled ) override; /** - * Function SetLayer() - * - * Sets the current routing layer. + * Set the current routing layer. */ bool SetLayer( int aLayer ) override; /** - * Function Traces() - * - * Returns the complete routed line, as a single-member ITEM_SET. + * Return the complete routed line, as a single-member ITEM_SET. */ const ITEM_SET Traces() override; /** - * Function CurrentEnd() - * - * Returns the current end of the line being placed. It may not be equal - * to the cursor position due to collisions. + * Return the current end of the line being placed. It may not be equal to the cursor + * position due to collisions. */ const VECTOR2I& CurrentEnd() const override { @@ -131,16 +116,12 @@ public: } /** - * Function CurrentNets() - * - * Returns the net code of currently routed track. + * Return the net code of currently routed track. */ const std::vector CurrentNets() const override; /** - * Function CurrentLayer() - * - * Returns the layer of currently routed track. + * Return the layer of currently routed track. */ int CurrentLayer() const override { @@ -148,25 +129,19 @@ public: } /** - * Function CurrentNode() - * - * Returns the most recent world state. + * Return the most recent world state. */ NODE* CurrentNode( bool aLoopsRemoved = false ) const override; /** - * Function FlipPosture() - * - * Toggles the current posture (straight/diagonal) of the trace head. + * Toggle the current posture (straight/diagonal) of the trace head. */ void FlipPosture() override; /** - * Function UpdateSizes() + * Perform on-the-fly update of the width, via diameter & drill size from a settings class. * - * Performs on-the-fly update of the width, via diameter & drill size from - * a settings class. Used to dynamically change these parameters as - * the track is routed. + * Used to dynamically change these parameters as the track is routed. */ void UpdateSizes( const SIZES_SETTINGS& aSizes ) override; @@ -181,44 +156,36 @@ private: int gap() const; /** - * Function route() + * Re-route the current track to point \a aP. * - * Re-routes the current track to point aP. Returns true, when routing has - * completed successfully (i.e. the trace end has reached point aP), and false - * if the trace was stuck somewhere on the way. May call routeStep() + * Returns true, when routing has completed successfully (i.e. the trace end has reached + * point aP), and false if the trace was stuck somewhere on the way. May call routeStep() * repetitively due to mouse smoothing. - * @param aP ending point of current route. - * @return true, if the routing is complete. + * + * @param aP is the ending point of current route. + * @return true if the routing is complete. */ bool route( const VECTOR2I& aP ); /** - * Function updateLeadingRatLine() - * - * Draws the "leading" ratsnest line, which connects the end of currently - * routed track and the nearest yet unrouted item. If the routing for - * current net is complete, draws nothing. + * Draw the "leading" ratsnest line, which connects the end of currently routed track and + * the nearest yet unrouted item. If the routing for current net is complete, draws nothing. */ void updateLeadingRatLine(); /** - * Function setWorld() - * - * Sets the board to route. + * Set the board to route. */ void setWorld( NODE* aWorld ); /** - * Function startPlacement() - * - * Initializes placement of a new line with given parameters. + * Initialize placement of a new line with given parameters. */ void initPlacement( ); /** - * Function setInitialDirection() + * Set preferred direction of the very first track segment to be laid. * - * Sets preferred direction of the very first track segment to be laid. * Used by posture switching mechanism. */ void setInitialDirection( const DIRECTION_45& aDirection ); @@ -227,13 +194,13 @@ private: bool routeHead( const VECTOR2I& aP ); bool tryWalkDp( NODE* aNode, DIFF_PAIR& aPair, bool aSolidsOnly ); - ///> route step, walkaround mode + ///< route step, walk around mode bool rhWalkOnly( const VECTOR2I& aP ); - ///> route step, shove mode + ///< route step, shove mode bool rhShoveOnly ( const VECTOR2I& aP ); - ///> route step, mark obstacles mode + ///< route step, mark obstacles mode bool rhMarkObstacles( const VECTOR2I& aP ); const VIA makeVia ( const VECTOR2I& aP, int aNet ); @@ -260,36 +227,36 @@ private: DP_PRIMITIVE_PAIR m_start; OPT m_prevPair; - ///> current algorithm iteration + ///< current algorithm iteration int m_iteration; - ///> pointer to world to search colliding items + ///< pointer to world to search colliding items NODE* m_world; - ///> current routing start point (end of tail, beginning of head) + ///< current routing start point (end of tail, beginning of head) VECTOR2I m_p_start; - ///> The shove engine + ///< The shove engine SHOVE* m_shove; - ///> Current world state + ///< Current world state NODE* m_currentNode; - ///> Postprocessed world state (including marked collisions & removed loops) + ///< Postprocessed world state (including marked collisions & removed loops) NODE* m_lastNode; SIZES_SETTINGS m_sizes; - ///> Are we placing a via? + ///< Are we placing a via? bool m_placingVia; - ///> current via diameter + ///< current via diameter int m_viaDiameter; - ///> current via drill + ///< current via drill int m_viaDrill; - ///> current track width + ///< current track width int m_currentWidth; int m_currentNet; diff --git a/pcbnew/router/pns_dp_meander_placer.h b/pcbnew/router/pns_dp_meander_placer.h index 21d4f07215..d290140e93 100644 --- a/pcbnew/router/pns_dp_meander_placer.h +++ b/pcbnew/router/pns_dp_meander_placer.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -41,8 +42,6 @@ namespace PNS { class ROUTER; /** - * DP_MEANDER_PLACER - * * Differential Pair length-matching/meandering tool. */ @@ -53,30 +52,24 @@ public: ~DP_MEANDER_PLACER(); /** - * Function Start() - * - * Starts routing a single track at point aP, taking item aStartItem as anchor + * Start routing a single track at point \a aP, taking item \a aStartItem as anchor * (unless NULL). */ bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override; /** - * Function Move() - * - * Moves the end of the currently routed trace to the point aP, taking - * aEndItem as anchor (if not NULL). - * (unless NULL). + * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as + * anchor (if not NULL). */ bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override; /** - * Function FixRoute() + * Commit the currently routed track to the parent node, taking \a aP as the final end + * point and \a aEndItem as the final anchor (if provided). * - * Commits the currently routed track to the parent node, taking - * aP as the final end point and aEndItem as the final anchor (if provided). - * @return true, if route has been commited. May return false if the routing - * result is violating design rules - in such case, the track is only committed - * if Settings.CanViolateDRC() is on. + * @return true if route has been committed. May return false if the routing result is + * violating design rules. In such cases, the track is only committed if + * Settings.CanViolateDRC() is on. */ bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish = false ) override; @@ -92,9 +85,7 @@ public: const LINE Trace() const; /** - * Function CurrentNode() - * - * Returns the most recent world state. + * Return the most recent world state. */ NODE* CurrentNode( bool aLoopsRemoved = false ) const override; @@ -125,16 +116,16 @@ private: const SEG baselineSegment( const DIFF_PAIR::COUPLED_SEGMENTS& aCoupledSegs ); bool pairOrientation( const DIFF_PAIR::COUPLED_SEGMENTS& aPair ); - + void setWorld( NODE* aWorld ); void release(); long long int origPathLength() const; - ///> current routing start point (end of tail, beginning of head) + ///< Current routing start point (end of tail, beginning of head). VECTOR2I m_currentStart; - ///> Current world state + ///< Current world state. NODE* m_currentNode; DIFF_PAIR m_originPair; diff --git a/pcbnew/router/pns_item.h b/pcbnew/router/pns_item.h index f5f5f6e761..f59ccb8892 100644 --- a/pcbnew/router/pns_item.h +++ b/pcbnew/router/pns_item.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2017 CERN - * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -46,17 +47,17 @@ enum LineMarker { /** - * ITEM + * Base class for PNS router board items. * - * Base class for PNS router board items. Implements the shared properties of all PCB items - - * net, spanned layers, geometric shape & refererence to owning model. + * Implements the shared properties of all PCB items net, spanned layers, geometric shape and + * reference to owning model. */ class ITEM { public: static const int UnusedNet = INT_MAX; - ///> Supported item types + ///< Supported item types enum PnsKind { SOLID_T = 1, @@ -97,17 +98,13 @@ public: virtual ~ITEM(); /** - * Function Clone() - * - * Returns a deep copy of the item + * Return a deep copy of the item. */ virtual ITEM* Clone() const = 0; /* - * Function Hull() + * Returns a convex polygon "hull" of a the item, that is used as the walk-around path. * - * Returns a convex polygon "hull" of a the item, that is used as the walk-around - * path. * @param aClearance defines how far from the body of the item the hull should be, * @param aWalkaroundThickness is the width of the line that walks around this hull. */ @@ -124,9 +121,7 @@ public: } /** - * Function Kind() - * - * Returns the type (kind) of the item + * Return the type (kind) of the item. */ PnsKind Kind() const { @@ -134,9 +129,7 @@ public: } /** - * Function OfKind() - * - * Returns true if the item's type matches the mask aKindMask. + * Return true if the item's type matches the mask \a aKindMask. */ bool OfKind( int aKindMask ) const { @@ -144,8 +137,6 @@ public: } /** - * Function KindStr() - * * Returns the kind of the item, as string */ std::string KindStr() const; @@ -163,10 +154,7 @@ public: virtual int Layer() const { return Layers().Start(); } /** - * Function LayersOverlap() - * - * Returns true if the set of layers spanned by aOther overlaps our - * layers. + * Return true if the set of layers spanned by aOther overlaps our layers. */ bool LayersOverlap( const ITEM* aOther ) const { @@ -174,22 +162,16 @@ public: } /** - * Function Owner() - * - * Returns the owner of this item, or NULL if there's none. + * Return the owner of this item, or NULL if there's none. */ NODE* Owner() const { return m_owner; } /** - * Functon SetOwner() - * - * Sets the node that owns this item. An item can belong to a single NODE or be unowned. + * Set the node that owns this item. An item can belong to a single NODE or be unowned. */ void SetOwner( NODE* aOwner ) { m_owner = aOwner; } /** - * Function BelongsTo() - * * @return true if the item is owned by the node aNode. */ bool BelongsTo( NODE* aNode ) const @@ -198,21 +180,18 @@ public: } /** - * Function Collide() + * Check for a collision (clearance violation) with between us and item \a aOther. * - * Checks for a collision (clearance violation) with between us and item aOther. - * Collision checking takes all PCB stuff into accound (layers, nets, DRC rules). + * Collision checking takes all PCB stuff into account (layers, nets, DRC rules). * Optionally returns a minimum translation vector for force propagation algorithm. * - * @param aOther item to check collision against + * @param aOther is the item to check collision against. * @return true, if a collision was found. */ bool Collide( const ITEM* aOther, const NODE* aNode, bool aDifferentNetsOnly = true ) const; /** - * Function Shape() - * - * Returns the geometrical shape of the item. Used for collision detection & spatial indexing. + * Return the geometrical shape of the item. Used for collision detection and spatial indexing. */ virtual const SHAPE* Shape() const { diff --git a/pcbnew/router/pns_joint.h b/pcbnew/router/pns_joint.h index f0156dd687..7dd350999a 100644 --- a/pcbnew/router/pns_joint.h +++ b/pcbnew/router/pns_joint.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -33,20 +34,18 @@ namespace PNS { /** - * JOINT + * Represents a 2D point on a given set of layers and belonging to a certain net, that links + * together a number of board items. * - * Represents a 2D point on a given set of layers and belonging to a certain - * net, that links together a number of board items. - * A hash table of joints is used by the router to follow connectivity between - * the items. + * A hash table of joints is used by the router to follow connectivity between the items. **/ class JOINT : public ITEM { public: typedef ITEM_SET::ENTRIES LINKED_ITEMS; - ///> Joints are hashed by their position, layers and net. - /// Linked items are, obviously, not hashed + ///< Joints are hashed by their position, layers and net. + ///< Linked items are, obviously, not hashed. struct HASH_TAG { VECTOR2I pos; @@ -96,8 +95,8 @@ public: return NULL; } - ///> Returns true if the joint is a trivial line corner, connecting two - /// segments of the same net, on the same layer. + ///< Return true if the joint is a trivial line corner, connecting two + ///< segments of the same net, on the same layer. bool IsLineCorner() const { if( m_linkedItems.Size() != 2 || m_linkedItems.Count( SEGMENT_T | ARC_T ) != 2 ) @@ -138,7 +137,7 @@ public: return seg1->Width() != seg2->Width(); } - ///> Links the joint to a given board item (when it's added to the NODE) + ///< Link the joint to a given board item (when it's added to the NODE). void Link( ITEM* aItem ) { if( m_linkedItems.Contains( aItem ) ) @@ -147,16 +146,16 @@ public: m_linkedItems.Add( aItem ); } - ///> Unlinks a given board item from the joint (upon its removal from a NODE) - ///> Returns true if the joint became dangling after unlinking. + ///< Unlink a given board item from the joint (upon its removal from a NODE) + ///< @return true if the joint became dangling after unlinking. bool Unlink( ITEM* aItem ) { m_linkedItems.Erase( aItem ); return m_linkedItems.Size() == 0; } - ///> For trivial joints, returns the segment adjacent to (aCurrent). For non-trival ones, returns - ///> NULL, indicating the end of line. + ///< For trivial joints, return the segment adjacent to (aCurrent). For non-trival ones, + ///< return NULL, indicating the end of line. LINKED_ITEM* NextSegment( ITEM* aCurrent ) const { if( !IsLineCorner() ) @@ -253,13 +252,13 @@ public: } private: - ///> hash tag for unordered_multimap + ///< hash tag for unordered_multimap HASH_TAG m_tag; - ///> list of items linked to this joint + ///< list of items linked to this joint ITEM_SET m_linkedItems; - ///> locked (non-movable) flag + ///< locked (non-movable) flag bool m_locked; }; diff --git a/pcbnew/router/pns_layerset.h b/pcbnew/router/pns_layerset.h index 948ee982a6..f3b9d3bb15 100644 --- a/pcbnew/router/pns_layerset.h +++ b/pcbnew/router/pns_layerset.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -25,9 +26,7 @@ #include /** - * LAYER_RANGE - * - * Represents a contiguous set of PCB layers. + * Represent a contiguous set of PCB layers. */ class LAYER_RANGE { @@ -106,7 +105,7 @@ public: m_end = aOther.m_end; } - ///> Shortcut for comparisons/overlap tests + ///< Shortcut for comparisons/overlap tests static LAYER_RANGE All() { return LAYER_RANGE( 0, 256 ); // fixme: use layer IDs header diff --git a/pcbnew/router/pns_line.h b/pcbnew/router/pns_line.h index bbb87a8a46..7d57b459fd 100644 --- a/pcbnew/router/pns_line.h +++ b/pcbnew/router/pns_line.h @@ -2,7 +2,8 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2017 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * Author: Tomasz Wlostowski * * This program is free software: you can redistribute it and/or modify it @@ -40,9 +41,9 @@ class LINKED_ITEM; class NODE; class VIA; +#define PNS_HULL_MARGIN 10 + /** - * LINE - * * Represents a track on a PCB, connecting two non-trivial joints (that is, * vias, pads, junctions between multiple traces or two traces different widths * and combinations of these). PNS_LINEs are NOT stored in the model (NODE). @@ -50,21 +51,16 @@ class VIA; * belongs to/starts/ends them. * * PNS_LINEs can be either loose (consisting of segments that do not belong to - * any NODE) or owned (with segments taken from a NODE) - these are - * returned by NODE::AssembleLine and friends. + * any NODE) or owned (with segments taken from a NODE) - these are returned by + * #NODE::AssembleLine and friends. * * A LINE may have a VIA attached at its end (i.e. the last point) - this is used by via * dragging/force propagation stuff. */ - -#define PNS_HULL_MARGIN 10 - class LINE : public LINK_HOLDER { public: - /** - * Constructor * Makes an empty line. */ LINE() : @@ -79,10 +75,8 @@ public: LINE( const LINE& aOther ); /** - * Constructor - * Copies properties (net, layers, etc.) from a base line and replaces the shape - * by another - **/ + * Copy properties (net, layers, etc.) from a base line and replaces the shape by another. + */ LINE( const LINE& aBase, const SHAPE_LINE_CHAIN& aLine ) : LINK_HOLDER( aBase ), m_line( aLine ), @@ -96,9 +90,7 @@ public: } /** - * Constructor - * Constructs a LINE for a lone VIA (ie a stitching via). - * @param aVia + * Construct a LINE for a lone VIA (ie a stitching via). */ LINE( const VIA& aVia ) : LINK_HOLDER( LINE_T ), @@ -130,17 +122,17 @@ public: return IsLinked() && LinkCount() == SegmentCount(); } - ///> Assigns a shape to the line (a polyline/line chain) + ///< Assign a shape to the line (a polyline/line chain). void SetShape( const SHAPE_LINE_CHAIN& aLine ) { m_line = aLine; m_line.SetWidth( m_width ); } - ///> Returns the shape of the line + ///< Return the shape of the line. const SHAPE* Shape() const override { return &m_line; } - ///> Modifiable accessor to the underlying shape + ///< Modifiable accessor to the underlying shape. SHAPE_LINE_CHAIN& Line() { return m_line; } const SHAPE_LINE_CHAIN& CLine() const { return m_line; } @@ -149,41 +141,43 @@ public: int ArcCount() const { return m_line.ArcCount(); } int ShapeCount() const { return m_line.ShapeCount(); } - ///> Returns the aIdx-th point of the line + ///< Return the \a aIdx-th point of the line. const VECTOR2I& CPoint( int aIdx ) const { return m_line.CPoint( aIdx ); } const SEG CSegment( int aIdx ) const { return m_line.CSegment( aIdx ); } - ///> Sets line width + ///< Set line width. void SetWidth( int aWidth ) { m_width = aWidth; m_line.SetWidth( aWidth ); } - ///> Returns line width + ///< Return line width. int Width() const { return m_width; } - ///> Returns true if the line is geometrically identical as line aOther + ///< Return true if the line is geometrically identical as line \a aOther. bool CompareGeometry( const LINE& aOther ); - ///> Reverses the point/vertex order + ///< Reverse the point/vertex order void Reverse(); - ///> Clips the line to the nearest obstacle, traversing from the line's start vertex (0). - ///> Returns the clipped line. + ///< Clip the line to the nearest obstacle, traversing from the line's start vertex (0). + ///< Returns the clipped line. const LINE ClipToNearestObstacle( NODE* aNode ) const; - ///> Clips the line to a given range of vertices. + ///< Clip the line to a given range of vertices. void ClipVertexRange ( int aStart, int aEnd ); - ///> Returns the number of corners of angles specified by mask aAngles. + ///< Return the number of corners of angles specified by mask aAngles. int CountCorners( int aAngles ) const; - ///> Calculates a line thightly wrapping a convex hull of an obstacle object (aObstacle). - ///> aPrePath = path from origin to the obstacle - ///> aWalkaroundPath = path around the obstacle - ///> aPostPath = past from obstacle till the end - ///> aCW = whether to walk around in clockwise or counter-clockwise direction. + /** + * Calculate a line tightly wrapping a convex hull of an obstacle object (aObstacle). + * @param aPrePath is the path from origin to the obstacle. + * @param aWalkaroundPath is the path around the obstacle. + * @param aPostPath is the path from obstacle till the end. + * @param aCW determines whether to walk around in clockwise or counter-clockwise direction. + */ bool Walkaround( SHAPE_LINE_CHAIN aObstacle, SHAPE_LINE_CHAIN& aPre, SHAPE_LINE_CHAIN& aWalk, SHAPE_LINE_CHAIN& aPost, bool aCw ) const; @@ -191,7 +185,7 @@ public: bool Is45Degree() const; - ///> Prints out all linked segments + ///< Print out all linked segments. void ShowLinks() const; bool EndsWithVia() const { return m_hasVia; } @@ -246,16 +240,16 @@ private: VECTOR2I snapDraggedCorner( const SHAPE_LINE_CHAIN& aPath, const VECTOR2I& aP, int aIndex ) const; - SHAPE_LINE_CHAIN m_line; ///> The actual shape of the line. - int m_width; ///> Our width. + SHAPE_LINE_CHAIN m_line; ///< The actual shape of the line. + int m_width; ///< Our width. - int m_snapThreshhold; ///> Width to smooth out jagged segments. + int m_snapThreshhold; ///< Width to smooth out jagged segments. - bool m_hasVia; ///> Optional via at the end point. + bool m_hasVia; ///< Optional via at the end point. VIA m_via; - ITEM* m_blockingObstacle; ///> For mark obstacle mode. + ITEM* m_blockingObstacle; ///< For mark obstacle mode. }; } diff --git a/pcbnew/router/pns_line_placer.h b/pcbnew/router/pns_line_placer.h index f14f5f8859..c891657592 100644 --- a/pcbnew/router/pns_line_placer.h +++ b/pcbnew/router/pns_line_placer.h @@ -3,7 +3,8 @@ * * Copyright (C) 2013-2017 CERN * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * + * @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 @@ -85,7 +86,7 @@ public: void SetTolerance( int toll ) { m_tolerance = toll; } - void SetDefaultDirections( DIRECTION_45 aInitDirection, DIRECTION_45 aLastSegDir ) + void SetDefaultDirections( DIRECTION_45 aInitDirection, DIRECTION_45 aLastSegDir ) { m_direction = aInitDirection; m_lastSegDirection = aLastSegDir; @@ -96,7 +97,7 @@ public: void FlipPosture(); /** - * Disables the mouse-trail portion of the posture solver; leaving only the manual posture + * Disable the mouse-trail portion of the posture solver; leaving only the manual posture * switch and the previous-segment posture algorithm */ void SetMouseDisabled( bool aDisabled = true ) { m_disableMouse = aDisabled; } @@ -114,10 +115,9 @@ private: }; /** - * LINE_PLACER + * Single track placement algorithm. * - * Single track placement algorithm. Interactively routes a track. - * Applies shove and walkaround algorithms when needed. + * Interactively routes a track and applies shove and walk around algorithms when needed. */ class LINE_PLACER : public PLACEMENT_ALGO @@ -127,29 +127,23 @@ public: ~LINE_PLACER(); /** - * Function Start() - * - * Starts routing a single track at point aP, taking item aStartItem as anchor - * (unless NULL). + * Start routing a single track at point aP, taking item aStartItem as anchor (unless NULL). */ bool Start( const VECTOR2I& aP, ITEM* aStartItem ) override; /** - * Function Move() - * - * Moves the end of the currently routed trace to the point aP, taking - * aEndItem as anchor (if not NULL). - * (unless NULL). + * Move the end of the currently routed trace to the point \a aP, taking \a aEndItem as + * anchor (if not NULL). */ bool Move( const VECTOR2I& aP, ITEM* aEndItem ) override; /** - * Function FixRoute() + * Commit the currently routed track to the parent node taking \a aP as the final end point + * and \a aEndItem as the final anchor (if provided). * - * Commits the currently routed track to the parent node, taking aP as the final end point - * and aEndItem as the final anchor (if provided). - * @return true, if route has been commited. May return false if the routing result is - * violating design rules - in such case, the track is only committed if CanViolateDRC() is on. + * @return true if route has been committed. May return false if the routing result is + * violating design rules. In such cases, the track is only committed if + * CanViolateDRC() is on. */ bool FixRoute( const VECTOR2I& aP, ITEM* aEndItem, bool aForceFinish ) override; @@ -162,54 +156,40 @@ public: bool HasPlacedAnything() const override; /** - * Function ToggleVia() - * - * Enables/disables a via at the end of currently routed trace. + * Enable/disable a via at the end of currently routed trace. */ bool ToggleVia( bool aEnabled ) override; /** - * Function SetLayer() - * - * Sets the current routing layer. + * Set the current routing layer. */ bool SetLayer( int aLayer ) override; /** - * Function Head() - * - * Returns the "head" of the line being placed, that is the volatile part that has not been + * Return the "head" of the line being placed, that is the volatile part that has not been * "fixed" yet. */ const LINE& Head() const { return m_head; } /** - * Function Tail() - * - * Returns the "tail" of the line being placed, the part which has already wrapped around + * Return the "tail" of the line being placed, the part which has already wrapped around * and shoved some obstacles. */ const LINE& Tail() const { return m_tail; } /** - * Function Trace() - * - * Returns the complete routed line. + * Return the complete routed line. */ const LINE Trace() const; /** - * Function Traces() - * - * Returns the complete routed line, as a single-member ITEM_SET. + * Return the complete routed line, as a single-member ITEM_SET. */ const ITEM_SET Traces() override; /** - * Function CurrentEnd() - * - * Returns the current end of the line being placed. It may not be equal - * to the cursor position due to collisions. + * Return the current end of the line being placed. It may not be equal to the cursor + * position due to collisions. */ const VECTOR2I& CurrentEnd() const override { @@ -217,9 +197,7 @@ public: } /** - * Function CurrentNet() - * - * Returns the net code of currently routed track. + * Return the net code of currently routed track. */ const std::vector CurrentNets() const override { @@ -227,9 +205,7 @@ public: } /** - * Function CurrentLayer() - * - * Returns the layer of currently routed track. + * Return the layer of currently routed track. */ int CurrentLayer() const override { @@ -237,23 +213,18 @@ public: } /** - * Function CurrentNode() - * - * Returns the most recent world state. + * Return the most recent world state. */ NODE* CurrentNode( bool aLoopsRemoved = false ) const override; /** - * Function FlipPosture() - * - * Toggles the current posture (straight/diagonal) of the trace head. + * Toggle the current posture (straight/diagonal) of the trace head. */ void FlipPosture() override; /** - * Function UpdateSizes() + * Perform on-the-fly update of the width, via diameter & drill size from a settings class. * - * Performs on-the-fly update of the width, via diameter & drill size from a settings class. * Used to dynamically change these parameters as the track is routed. */ void UpdateSizes( const SIZES_SETTINGS& aSizes ) override; @@ -265,145 +236,123 @@ public: void GetModifiedNets( std::vector& aNets ) const override; /** - * Function SplitAdjacentSegments() - * - * Checks if point aP lies on segment aSeg. If so, splits the segment in two, forming a - * joint at aP and stores updated topology in node aNode. + * Check if point \a aP lies on segment \a aSeg. If so, splits the segment in two, forming a + * joint at \a aP and stores updated topology in node \a aNode. */ bool SplitAdjacentSegments( NODE* aNode, ITEM* aSeg, const VECTOR2I& aP ); private: /** - * Function route() - * - * Re-routes the current track to point aP. Returns true, when routing has completed - * successfully (i.e. the trace end has reached point aP), and false if the trace was + * Re-route the current track to point aP. Returns true, when routing has completed + * successfully (i.e. the trace end has reached point \a aP), and false if the trace was * stuck somewhere on the way. May call routeStep() repetitively due to mouse smoothing. + * * @param aP ending point of current route. * @return true, if the routing is complete. */ bool route( const VECTOR2I& aP ); /** - * Function updateLeadingRatLine() - * - * Draws the "leading" ratsnest line, which connects the end of currently routed track and + * Draw the "leading" rats nest line, which connects the end of currently routed track and * the nearest yet unrouted item. If the routing for current net is complete, draws nothing. */ void updateLeadingRatLine(); /** - * Function setWorld() - * - * Sets the board to route. + * Set the board to route. */ void setWorld( NODE* aWorld ); /** - * Function startPlacement() - * - * Initializes placement of a new line with given parameters. + * Initialize placement of a new line with given parameters. */ void initPlacement(); /** - * Function setInitialDirection() - * - * Sets preferred direction of the very first track segment to be laid. + * Set preferred direction of the very first track segment to be laid. * Used by posture switching mechanism. */ void setInitialDirection( const DIRECTION_45& aDirection ); /** - * Function removeLoops() - * * Searches aNode for traces concurrent to aLatest and removes them. Updated * topology is stored in aNode. */ void removeLoops( NODE* aNode, LINE& aLatest ); /** - * Assembles a line starting from segment or arc aLatest, removes collinear segments - * and redundant vertexes. If a simplification bhas been found, replaces the - * old line with the simplified one in aNode. + * Assemble a line starting from segment or arc aLatest, removes collinear segments + * and redundant vertexes. If a simplification has been found, replaces the old line + * with the simplified one in \a aNode. */ void simplifyNewLine( NODE* aNode, LINKED_ITEM* aLatest ); /** - * Function handleSelfIntersections() + * Check if the head of the track intersects its tail. If so, cuts the tail up to the + * intersecting segment and fixes the head direction to match the last segment before + * the cut. * - * Checks if the head of the track intersects its tail. If so, cuts the - * tail up to the intersecting segment and fixes the head direction to match - * the last segment before the cut. * @return true if the line has been changed. */ bool handleSelfIntersections(); /** - * Function handlePullback() + * Deal with pull-back: reduces the tail if head trace is moved backwards wrs to the + * current tail direction. * - * Deals with pull-back: reduces the tail if head trace is moved backwards - * wrs to the current tail direction. * @return true if the line has been changed. */ bool handlePullback(); /** - * Function mergeHead() + * Moves "established" segments from the head to the tail if certain conditions are met. * - * Moves "estabished" segments from the head to the tail if certain - * conditions are met. * @return true, if the line has been changed. */ bool mergeHead(); /** - * Function reduceTail() + * Attempt to reduce the number of segments in the tail by trying to replace a certain + * number of latest tail segments with a direct trace leading to \a aEnd that does not + * collide with anything. * - * Attempts to reduce the numer of segments in the tail by trying to replace a - * certain number of latest tail segments with a direct trace leading to aEnd - * that does not collide with anything. - * @param aEnd: current routing destination point. + * @param aEnd is the current routing destination point. * @return true if the line has been changed. */ bool reduceTail( const VECTOR2I& aEnd ); /** - * Function optimizeTailHeadTransition() + * Try to reduce the corner count of the most recent part of tail/head by merging + * obtuse/collinear segments. * - * Tries to reduce the corner count of the most recent part of tail/head by - * merging obtuse/collinear segments. - * @return true, if the line has been changed. + * @return true if the line has been changed. */ bool optimizeTailHeadTransition(); /** - * Function routeHead() - * - * Computes the head trace between the current start point (m_p_start) and - * point aP, starting with direction defined in m_direction. The trace walks - * around all colliding solid or non-movable items. Movable segments are - * ignored, as they'll be handled later by the shove algorithm. + * Compute the head trace between the current start point (m_p_start) and point \a aP, + * starting with direction defined in m_direction. The trace walks around all + * colliding solid or non-movable items. Movable segments are ignored, as they'll be + * handled later by the shove algorithm. */ - bool routeHead( const VECTOR2I& aP, LINE& aNewHead); + bool routeHead( const VECTOR2I& aP, LINE& aNewHead ); /** - * Function routeStep() + * Perform a single routing algorithm step, for the end point \a aP. * - * Performs a single routing alorithm step, for the end point aP. - * @param aP ending point of current route - * @return true, if the line has been changed. + * @param aP is the ending point of current route. + * @return true if the line has been changed. */ void routeStep( const VECTOR2I& aP ); - ///> route step, walkaround mode - bool rhWalkOnly( const VECTOR2I& aP, LINE& aNewHead); + ///< Route step walk around mode. + bool rhWalkOnly( const VECTOR2I& aP, LINE& aNewHead ); - ///> route step, shove mode - bool rhShoveOnly( const VECTOR2I& aP, LINE& aNewHead); + ///< Route step shove mode. + bool rhShoveOnly( const VECTOR2I& aP, LINE& aNewHead ); - ///> route step, mark obstacles mode + ///< Route step mark obstacles mode. bool rhMarkObstacles( const VECTOR2I& aP, LINE& aNewHead ); const VIA makeVia( const VECTOR2I& aP ); @@ -411,23 +360,23 @@ private: bool buildInitialLine( const VECTOR2I& aP, LINE& aHead ); - DIRECTION_45 m_direction; ///> current routing direction - DIRECTION_45 m_initial_direction; ///> routing direction for new traces + DIRECTION_45 m_direction; ///< current routing direction + DIRECTION_45 m_initial_direction; ///< routing direction for new traces - LINE m_head; ///> the volatile part of the track from the previously - ///> analyzed point to the current routing destination + LINE m_head; ///< the volatile part of the track from the previously + ///< analyzed point to the current routing destination - LINE m_tail; ///> routing "tail": part of the track that has been already - ///> fixed due to collisions with obstacles + LINE m_tail; ///< routing "tail": part of the track that has been already + ///< fixed due to collisions with obstacles - NODE* m_world; ///> pointer to world to search colliding items - VECTOR2I m_p_start; ///> current routing start (end of tail, beginning of head) + NODE* m_world; ///< pointer to world to search colliding items + VECTOR2I m_p_start; ///< current routing start (end of tail, beginning of head) - std::unique_ptr m_shove; ///> The shove engine + std::unique_ptr m_shove; ///< The shove engine - NODE* m_currentNode; ///> Current world state - NODE* m_lastNode; ///> Postprocessed world state (including marked collisions & - ///> removed loops) + NODE* m_currentNode; ///< Current world state + NODE* m_lastNode; ///< Postprocessed world state (including marked collisions & + ///< removed loops) SIZES_SETTINGS m_sizes; diff --git a/pcbnew/router/pns_link_holder.h b/pcbnew/router/pns_link_holder.h index 1c8ea86265..307bd15048 100644 --- a/pcbnew/router/pns_link_holder.h +++ b/pcbnew/router/pns_link_holder.h @@ -2,6 +2,8 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2019 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * Author: Seth Hillbrand * Author: Tomasz Wlostowski * @@ -36,14 +38,14 @@ public: LINK_HOLDER( PnsKind aKind ) : ITEM( aKind ) {} - ///> Adds a reference to an item registered in a NODE that is a part of this line. + ///< Add a reference to an item registered in a #NODE that is a part of this line. void Link( LINKED_ITEM* aLink ) { m_links.push_back( aLink ); } - ///> Returns the list of links from the owning node that constitute this - ///> line (or NULL if the line is not linked) + ///< Return the list of links from the owning node that constitute this + ///< line (or NULL if the line is not linked). LINKS& Links() { return m_links; } const LINKS& Links() const { return m_links; } @@ -52,7 +54,7 @@ public: return m_links.size() != 0; } - ///> Checks if the segment aLink is a part of the line. + ///< Check if the segment aLink is a part of the line. bool ContainsLink( const LINKED_ITEM* aItem ) const { return alg::contains( m_links, aItem ); @@ -63,13 +65,13 @@ public: return m_links[aIndex]; } - ///> Erases the linking information. Used to detach the line from the owning node. + ///< Erase the linking information. Used to detach the line from the owning node. virtual void ClearLinks() { m_links.clear(); } - ///> Returns the number of segments that were assembled together to form this line. + ///< Return the number of segments that were assembled together to form this line. int LinkCount() const { return m_links.size(); @@ -77,7 +79,7 @@ public: void ShowLinks() const { - #if 0 // fixme: move outside header +#if 0 /// @todo move outside header. if( !IsLinked() ) { wxLogTrace( "PNS", "item %p: no links", this ); @@ -88,18 +90,18 @@ public: for( int i = 0; i < (int) m_links.size(); i++ ) wxLogTrace( "PNS", "item %d: %p\n", i, m_links[i] ); - #endif +#endif } protected: - ///> Copies m_links from the line aParent. + ///< Copy m_links from the line \a aParent. void copyLinks( const LINK_HOLDER* aParent ) { m_links = aParent->m_links; } - ///> List of segments in the owning NODE (ITEM::m_owner) that constitute this line, or NULL - ///> if the line is not a part of any node. + ///< List of segments in the owning NODE (ITEM::m_owner) that constitute this line, or NULL + ///< if the line is not a part of any node. LINKS m_links; }; diff --git a/pcbnew/router/pns_meander.h b/pcbnew/router/pns_meander.h index 5dbe1d76af..8e3965bfea 100644 --- a/pcbnew/router/pns_meander.h +++ b/pcbnew/router/pns_meander.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2015 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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,8 +31,9 @@ namespace PNS { class MEANDER_PLACER_BASE; +class MEANDERED_LINE; -///< Shapes of available meanders +///< Shapes of available meanders. enum MEANDER_TYPE { MT_SINGLE, // _|^|_, single-sided MT_START, // _|^| @@ -43,16 +45,14 @@ enum MEANDER_TYPE { MT_EMPTY // no meander (straight line) }; -///> meander corner shape +///< Meander corner shape. enum MEANDER_STYLE { MEANDER_STYLE_ROUND = 1, // rounded (90 degree arc) MEANDER_STYLE_CHAMFER // chamfered (45 degree segment) }; /** - * MEANDER_SETTINGS - * - * Holds dimensions for the meandering algorithm. + * Dimensions for the meandering algorithm. */ class MEANDER_SETTINGS { @@ -73,47 +73,41 @@ public: m_cornerArcSegments = 8; } - ///> minimum meandering amplitude + ///< Minimum meandering amplitude. int m_minAmplitude; - ///> maximum meandering amplitude + ///< Maximum meandering amplitude. int m_maxAmplitude; - ///> meandering period/spacing (see dialog picture for explanation) + ///< Meandering period/spacing (see dialog picture for explanation). int m_spacing; - ///> amplitude/spacing adjustment step + ///< Amplitude/spacing adjustment step. int m_step; - ///> length PadToDie + ///< Length PadToDie. int m_lenPadToDie; - ///> desired length of the tuned line/diff pair (this is in nm, so allow more than board width) + ///< Desired length of the tuned line/diff pair (this is in nm, so allow more than board width). long long int m_targetLength; - ///> type of corners for the meandered line + ///< Type of corners for the meandered line. MEANDER_STYLE m_cornerStyle; - ///> rounding percentage (0 - 100) + ///< Rounding percentage (0 - 100). int m_cornerRadiusPercentage; - ///> allowable tuning error + ///< Allowable tuning error. int m_lengthTolerance; - ///> number of line segments for arc approximation + ///< Number of line segments for arc approximation. int m_cornerArcSegments; - ///> target skew value for diff pair de-skewing + ///< Target skew value for diff pair de-skewing. int m_targetSkew; }; -class MEANDERED_LINE; - /** - * MEANDER_SETTINGS - * - * Holds the geometry of a single meander. + * The geometry of a single meander. */ class MEANDER_SHAPE { public: /** - * Constructor - * - * @param aPlacer the meander placer instance - * @param aWidth width of the meandered line + * @param aPlacer the meander placer instance. + * @param aWidth width of the meandered line. * @param aIsDual when true, the shape contains two meandered - * lines at a given offset (diff pairs) + * lines at a given offset (diff pairs). */ MEANDER_SHAPE( MEANDER_PLACER_BASE* aPlacer, int aWidth, bool aIsDual = false ) : m_placer( aPlacer ), @@ -121,7 +115,7 @@ public: m_width( aWidth ), m_baselineOffset( 0 ) { - // Do not leave unitialized members, and keep static analyser quiet: + // Do not leave uninitialized members, and keep static analyzer quiet: m_type = MT_SINGLE; m_amplitude = 0; m_side = false; @@ -131,9 +125,7 @@ public: } /** - * Function SetType() - * - * Sets the type of the meander. + * Set the type of the meander. */ void SetType( MEANDER_TYPE aType ) { @@ -141,8 +133,6 @@ public: } /** - * Function Type() - * * @return the type of the meander. */ MEANDER_TYPE Type() const @@ -151,9 +141,7 @@ public: } /** - * Function SetBaseIndex() - * - * Sets an auxillary index of the segment being meandered in its original LINE. + * Set an auxiliary index of the segment being meandered in its original LINE. */ void SetBaseIndex( int aIndex ) { @@ -161,9 +149,7 @@ public: } /** - * Function BaseIndex() - * - * @return auxillary index of the segment being meandered in its original LINE. + * @return auxiliary index of the segment being meandered in its original LINE. */ int BaseIndex() const { @@ -171,8 +157,6 @@ public: } /** - * Function Amplitude() - * * @return the amplitude of the meander shape. */ int Amplitude() const @@ -181,34 +165,28 @@ public: } /** - * Function MakeCorner() - * - * Creates a dummy meander shape representing a line corner. Used to define + * Create a dummy meander shape representing a line corner. Used to define * the starts/ends of meandered segments. - * @param aP1 corner point of the 1st line - * @param aP2 corner point of the 2nd line (if m_dual == true) + * + * @param aP1 corner point of the 1st line. + * @param aP2 corner point of the 2nd line (if m_dual == true). */ void MakeCorner( VECTOR2I aP1, VECTOR2I aP2 = VECTOR2I( 0, 0 ) ); /** - * Function Resize() + * Change the amplitude of the meander shape to aAmpl and recalculates the resulting + * line chain. * - * Changes the amplitude of the meander shape to aAmpl and recalculates - * the resulting line chain. * @param aAmpl new amplitude. */ void Resize( int aAmpl ); /** - * Function Recalculate() - * - * Recalculates the line chain representing the meanders's shape. + * Recalculate the line chain representing the meander's shape. */ void Recalculate(); /** - * Function IsDual() - * * @return true if the shape represents 2 parallel lines (diff pair). */ bool IsDual() const @@ -217,8 +195,6 @@ public: } /** - * Function Side() - * * @return true if the meander is to the right of its base segment. */ bool Side() const @@ -227,8 +203,6 @@ public: } /** - * Function End() - * * @return end vertex of the base segment of the meander shape. */ VECTOR2I End() const @@ -237,8 +211,6 @@ public: } /** - * Function CLine() - * * @return the line chain representing the shape of the meander. */ const SHAPE_LINE_CHAIN& CLine( int aShape ) const @@ -247,30 +219,25 @@ public: } /** - * Function MakeEmpty() - * - * Replaces the meander with straight bypass line(s), effectively - * clearing it. + * Replace the meander with straight bypass line(s), effectively clearing it. */ void MakeEmpty(); /** - * Function Fit() + * Attempt to fit a meander of a given type onto a segment, avoiding collisions with other + * board features. * - * Attempts to fit a meander of a given type onto a segment, avoiding - * collisions with other board features. - * @param aType type of meander shape - * @param aSeg base segment for meandering - * @param aP start point of the meander - * @param aSide side of aSeg to put the meander on (true = right) + * @param aType type of meander shape. + * @param aSeg base segment for meandering. + * @param aP start point of the meander. + * @param aSide side of aSeg to put the meander on (true = right). * @return true on success. */ bool Fit( MEANDER_TYPE aType, const SEG& aSeg, const VECTOR2I& aP, bool aSide ); /** - * Function BaseSegment() + * Return the base segment the meander was fitted to. * - * Returns the base segment the meadner was fitted to. * @return the base segment. */ const SEG& BaseSegment() const @@ -279,30 +246,21 @@ public: } /** - * Function BaselineLength() - * - * @return length of the base segment for the meander (i.e. - * the minimum tuned length. + * @return length of the base segment for the meander (i.e.the minimum tuned length). */ int BaselineLength() const; /** - * Function MaxTunableLength() - * * @return the length of the fitted line chain. */ int MaxTunableLength() const; /** - * Function Settings() - * * @return the current meandering settings. */ const MEANDER_SETTINGS& Settings() const; /** - * Function Width() - * * @return width of the meandered line. */ int Width() const @@ -311,11 +269,10 @@ public: } /** - * Function SetBaselineOffset() + * Set the parallel offset between the base segment and the meandered line. Used for + * dual meanders (diff pair) only. * - * Sets the parallel offset between the base segment and the meandered - * line. Used for dual menaders (diff pair) only. - * @param aOffset the offset + * @param aOffset the offset. */ void SetBaselineOffset( int aOffset ) { @@ -325,82 +282,99 @@ public: private: friend class MEANDERED_LINE; - ///> starts turtle drawing + ///< Start turtle drawing void start( SHAPE_LINE_CHAIN* aTarget, const VECTOR2D& aWhere, const VECTOR2D& aDir ); - ///> moves turtle forward by aLength + + ///< Move turtle forward by \a aLength. void forward( int aLength ); - ///> turns the turtle by aAngle + + ///< Turn the turtle by \a aAngle void turn( int aAngle ); - ///> tells the turtle to draw a mitered corner of given radius and turn direction + + ///< Tell the turtle to draw a mitered corner of given radius and turn direction. void miter( int aRadius, bool aSide ); - ///> tells the turtle to draw an U-like shape + + ///< Tell the turtle to draw an U-like shape. void uShape( int aSides, int aCorner, int aTop ); - ///> generates a 90-degree circular arc + ///< Generate a 90-degree circular arc. SHAPE_LINE_CHAIN makeMiterShape( VECTOR2D aP, VECTOR2D aDir, bool aSide ); - ///> reflects a point onto other side of a given segment + ///< Reflect a point onto other side of a given segment. VECTOR2I reflect( VECTOR2I aP, const SEG& aLine ); - ///> produces a meander shape of given type - SHAPE_LINE_CHAIN genMeanderShape( VECTOR2D aP, VECTOR2D aDir, bool aSide, MEANDER_TYPE aType, int aAmpl, int aBaselineOffset = 0 ); + ///< Produce a meander shape of given type. + SHAPE_LINE_CHAIN genMeanderShape( VECTOR2D aP, VECTOR2D aDir, bool aSide, MEANDER_TYPE aType, + int aAmpl, int aBaselineOffset = 0 ); - ///> recalculates the clipped baseline after the parameters of - ///> the meander have been changed. + ///< Recalculate the clipped baseline after the parameters of the meander have been changed. void updateBaseSegment(); - ///> returns sanitized corner radius value + ///< Return sanitized corner radius value. int cornerRadius() const; - ///> returns sanitized spacing value + ///< Return sanitized spacing value. int spacing() const; - ///> the type + ///< The type of meander. MEANDER_TYPE m_type; - ///> the placer that placed this meander + + ///< The placer that placed this meander. MEANDER_PLACER_BASE* m_placer; - ///> dual or single line + + ///< Dual or single line. bool m_dual; - ///> width of the line + + ///< Width of the line. int m_width; - ///> amplitude of the meander + + ///< Amplitude of the meander. int m_amplitude; - ///> offset wrs the base segment (dual only) + + ///< Offset wrs the base segment (dual only). int m_baselineOffset; - ///> average radius of meander corners (for correction of DP meanders) + + ///< Average radius of meander corners (for correction of DP meanders). int m_meanCornerRadius; - ///> first point of the meandered line + + ///< First point of the meandered line. VECTOR2I m_p0; - ///> base segment (unclipped) + + ///< Base segment (unclipped). SEG m_baseSeg; - ///> base segment (clipped) + + ///< Base segment (clipped). SEG m_clippedBaseSeg; - ///> side (true = right) + + ///< Side (true = right). bool m_side; - ///> the actual shapes (0 used for single, both for dual) + + ///< The actual shapes (0 used for single, both for dual). SHAPE_LINE_CHAIN m_shapes[2]; - ///> index of the meandered segment in the base line + + ///< Index of the meandered segment in the base line. int m_baseIndex; - ///> current turtle direction + + ///< The current turtle direction. VECTOR2D m_currentDir; - ///> current turtle position + + ///< The current turtle position. VECTOR2D m_currentPos; - ///> the line the turtle is drawing on + + ///< The line the turtle is drawing on. SHAPE_LINE_CHAIN* m_currentTarget; }; /** - * MEANDERED_LINE - * - * Represents a set of meanders fitted over a single or two lines. + * Represent a set of meanders fitted over a single or two lines. */ class MEANDERED_LINE { public: MEANDERED_LINE() { - // Do not leave unitialized members, and keep static analyser quiet: + // Do not leave uninitialized members, and keep static analyzer quiet: m_placer = NULL; m_dual = false; m_width = 0; @@ -408,8 +382,6 @@ public: } /** - * Constructor - * * @param aPlacer the meander placer instance * @param aIsDual when true, the meanders are generated for two coupled lines */ @@ -417,7 +389,7 @@ public: m_placer( aPlacer ), m_dual( aIsDual ) { - // Do not leave unitialized members, and keep static analyser quiet: + // Do not leave uninitialized members, and keep static analyzer quiet: m_width = 0; m_baselineOffset = 0; } @@ -428,34 +400,28 @@ public: } /** - * Function AddCorner() + * Create a dummy meander shape representing a line corner. Used to define the starts/ends + * of meandered segments. * - * Creates a dummy meander shape representing a line corner. Used to define - * the starts/ends of meandered segments. - * @param aA corner point of the 1st line - * @param aB corner point of the 2nd line (if m_dual == true) + * @param aA corner point of the 1st line. + * @param aB corner point of the 2nd line (if m_dual == true). */ void AddCorner( const VECTOR2I& aA, const VECTOR2I& aB = VECTOR2I( 0, 0 ) ); /** - * Function AddMeander() + * Add a new meander shape the the meandered line. * - * Adds a new meander shape the the meandered line. * @param aShape the meander shape to add */ void AddMeander( MEANDER_SHAPE* aShape ); /** - * Function Clear() - * - * Clears the line geometry, removing all corners and meanders. + * Clear the line geometry, removing all corners and meanders. */ void Clear(); /** - * Function SetWidth() - * - * Sets the line width. + * Set the line width. */ void SetWidth( int aWidth ) { @@ -463,12 +429,10 @@ public: } /** - * Function MeanderSegment() + * Fit maximum amplitude meanders on a given segment and adds to the current line. * - * Fits maximum amplitude meanders on a given segment and adds to the - * current line. - * @param aSeg the base segment to meander - * @param aBaseIndex index of the base segment in the original line + * @param aSeg the base segment to meander. + * @param aBaseIndex index of the base segment in the original line. */ void MeanderSegment( const SEG& aSeg, int aBaseIndex = 0 ); @@ -479,9 +443,7 @@ public: } /** - * Function Meanders() - * - * @return set of meander shapes for this line + * @return set of meander shapes for this line. */ std::vector& Meanders() { @@ -489,19 +451,15 @@ public: } /** - * Function CheckSelfIntersections() + * Check if the given shape is intersecting with any other meander in the current line. * - * Checks if the given shape is intersecting with any other meander in - * the current line. - * @param aShape the shape to check - * @param aClearance clearance value - * @return true, if the meander shape is not colliding + * @param aShape the shape to check. + * @param aClearance clearance value. + * @return true, if the meander shape is not colliding. */ bool CheckSelfIntersections( MEANDER_SHAPE* aShape, int aClearance ); /** - * Function Settings() - * * @return the current meandering settings. */ const MEANDER_SETTINGS& Settings() const; diff --git a/pcbnew/router/pns_meander_placer.h b/pcbnew/router/pns_meander_placer.h index 6a4d14b36a..8d5e7fea7b 100644 --- a/pcbnew/router/pns_meander_placer.h +++ b/pcbnew/router/pns_meander_placer.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -41,8 +42,6 @@ class SHOVE; class OPTIMIZER; /** - * MEANDER_PLACER - * * Single track length matching/meandering tool. */ class MEANDER_PLACER : public MEANDER_PLACER_BASE @@ -104,10 +103,10 @@ protected: virtual long long int origPathLength() const; - ///> current routing start point (end of tail, beginning of head) + ///< current routing start point (end of tail, beginning of head) VECTOR2I m_currentStart; - ///> Current world state + ///< Current world state NODE* m_currentNode; LINE m_originLine; diff --git a/pcbnew/router/pns_meander_placer_base.h b/pcbnew/router/pns_meander_placer_base.h index c77b8dcb07..0d02d60898 100644 --- a/pcbnew/router/pns_meander_placer_base.h +++ b/pcbnew/router/pns_meander_placer_base.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2015 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -40,15 +41,13 @@ class SHOVE; class OPTIMIZER; /** - * MEANDER_PLACER_BASE - * - * Base class for Single trace & Differenial pair meandering tools, as - * both of them share a lot of code. + * Base class for Single trace & Differential pair meandering tools, as both of them share a + * lot of code. */ class MEANDER_PLACER_BASE : public PLACEMENT_ALGO { public: - ///> Result of the length tuning operation + ///< Result of the length tuning operation enum TUNING_STATUS { TOO_SHORT = 0, TOO_LONG, @@ -59,61 +58,49 @@ public: virtual ~MEANDER_PLACER_BASE(); /** - * Function TuningInfo() - * - * Returns a string describing the status and length of the - * tuned traces. + * Return a string describing the status and length of the tuned traces. */ virtual const wxString TuningInfo( EDA_UNITS aUnits ) const = 0; /** - * Function TuningStatus() - * - * Returns the tuning status (too short, too long, etc.) - * of the trace(s) being tuned. + * Return the tuning status (too short, too long, etc.) of the trace(s) being tuned. */ virtual TUNING_STATUS TuningStatus() const = 0; /** - * Function AmplitudeStep() + * Increase/decreases the current meandering amplitude by one step. * - * Increases/decreases the current meandering amplitude by one step. * @param aSign direction (negative = decrease, positive = increase). */ virtual void AmplitudeStep( int aSign ); /** - * Function SpacingStep() + * Increase/decrease the current meandering spacing by one step. * - * Increases/decreases the current meandering spcing by one step. * @param aSign direction (negative = decrease, positive = increase). */ virtual void SpacingStep( int aSign ); /** - * Function MeanderSettings() + * Return the current meandering configuration. * - * Returns the current meandering configuration. * @return the settings */ virtual const MEANDER_SETTINGS& MeanderSettings() const; /* - * Function UpdateSettings() + * Set the current meandering configuration. * - * Sets the current meandering configuration. - * @param aSettings the settings + * @param aSettings the settings. */ virtual void UpdateSettings( const MEANDER_SETTINGS& aSettings); /** - * Function CheckFit() + * Checks if it's OK to place the shape aShape (i.e. if it doesn't cause DRC violations + * or collide with other meanders). * - * Checks if it's ok to place the shape aShape (i.e. - * if it doesn't cause DRC violations or collide with - * other meanders). - * @param aShape the shape to check - * @return true if the shape fits + * @param aShape the shape to check. + * @return true if the shape fits. */ virtual bool CheckFit( MEANDER_SHAPE* aShape ) { @@ -123,55 +110,48 @@ public: int GetTotalPadToDieLength( const LINE& aLine ) const; protected: - /** - * Function cutTunedLine() + * Extract the part of a track to be meandered, depending on the starting point and the + * cursor position. * - * Extracts the part of a track to be meandered, depending on the - * starting point and the cursor position. - * @param aOrigin the original line - * @param aTuneStart point where we start meandering (start click coorinates) - * @param aCursorPos current cursor position - * @param aPre part before the beginning of meanders - * @param aTuned part to be meandered - * @param aPost part after the end of meanders + * @param aOrigin the original line. + * @param aTuneStart point where we start meandering (start click coordinates). + * @param aCursorPos current cursor position. + * @param aPre part before the beginning of meanders. + * @param aTuned part to be meandered. + * @param aPost part after the end of meanders. */ - void cutTunedLine( const SHAPE_LINE_CHAIN& aOrigin, - const VECTOR2I& aTuneStart, - const VECTOR2I& aCursorPos, - SHAPE_LINE_CHAIN& aPre, - SHAPE_LINE_CHAIN& aTuned, - SHAPE_LINE_CHAIN& aPost ); + void cutTunedLine( const SHAPE_LINE_CHAIN& aOrigin, const VECTOR2I& aTuneStart, + const VECTOR2I& aCursorPos, SHAPE_LINE_CHAIN& aPre, SHAPE_LINE_CHAIN& aTuned, + SHAPE_LINE_CHAIN& aPost ); /** - * Function tuneLineLength() - * - * Takes a set of meanders in aTuned and tunes their length to - * extend the original line length by aElongation. + * Take a set of meanders in \a aTuned and tunes their length to extend the original line + * length by \a aElongation. */ void tuneLineLength( MEANDERED_LINE& aTuned, long long int aElongation ); /** - * Function compareWithTolerance() - * - * Compares aValue against aExpected with given tolerance. + * Compare \a aValue against \a aExpected with given tolerance. */ - int compareWithTolerance( - long long int aValue, long long int aExpected, long long int aTolerance = 0 ) const; + int compareWithTolerance( long long int aValue, long long int aExpected, + long long int aTolerance = 0 ) const; VECTOR2I getSnappedStartPoint( LINKED_ITEM* aStartItem, VECTOR2I aStartPoint ); - ///> pointer to world to search colliding items + ///< Pointer to world to search colliding items. NODE* m_world; - ///> total length added by pad to die size + ///< Total length added by pad to die size. int m_padToDieLenth; - ///> width of the meandered trace(s) + ///< Width of the meandered trace(s). int m_currentWidth; - ///> meandering settings + + ///< Meander settings. MEANDER_SETTINGS m_settings; - ///> current end point + + ///< The current end point. VECTOR2I m_currentEnd; }; diff --git a/pcbnew/router/pns_node.cpp b/pcbnew/router/pns_node.cpp index 638f3ed8a9..f333b6f512 100644 --- a/pcbnew/router/pns_node.cpp +++ b/pcbnew/router/pns_node.cpp @@ -3,7 +3,8 @@ * * Copyright (C) 2013-2019 CERN * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * + * @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 @@ -132,7 +133,7 @@ NODE* NODE::Branch() child->m_root = isRoot() ? this : m_root; child->m_maxClearance = m_maxClearance; - // Immmediate offspring of the root branch needs not copy anything. For the rest, deep-copy + // Immediate offspring of the root branch needs not copy anything. For the rest, deep-copy // joints, overridden item maps and pointers to stored items. if( !isRoot() ) { @@ -183,7 +184,7 @@ void OBSTACLE_VISITOR::SetWorld( const NODE* aNode, const NODE* aOverride ) bool OBSTACLE_VISITOR::visit( ITEM* aCandidate ) { - // check if there is a more recent branch with a newer (possibily modified) version of this + // check if there is a more recent branch with a newer (possibly modified) version of this // item. if( m_override && m_override->Overrides( aCandidate ) ) return true; @@ -197,7 +198,7 @@ struct NODE::DEFAULT_OBSTACLE_VISITOR : public OBSTACLE_VISITOR { OBSTACLES& m_tab; - int m_kindMask; ///> (solids, vias, segments, etc...) + int m_kindMask; ///< (solids, vias, segments, etc...) int m_limitCount; int m_matchCount; int m_extraClearance; @@ -714,6 +715,7 @@ void NODE::rebuildJoint( JOINT* aJoint, ITEM* aItem ) tag.pos = aJoint->Pos(); bool split; + do { split = false; @@ -736,7 +738,7 @@ void NODE::rebuildJoint( JOINT* aJoint, ITEM* aItem ) } while( split ); // and re-link them, using the former via's link list - for(ITEM* link : links) + for( ITEM* link : links ) { if( link != aItem ) linkJoint( tag.pos, link->Layers(), net, link ); @@ -844,7 +846,7 @@ void NODE::Remove( ITEM* aItem ) void NODE::Remove( LINE& aLine ) { - // LINE does not have a seperate remover, as LINEs are never truly a member of the tree + // LINE does not have a separate remover, as LINEs are never truly a member of the tree std::vector& segRefs = aLine.Links(); for( LINKED_ITEM* li : segRefs ) @@ -1162,10 +1164,11 @@ void NODE::Dump( bool aLong ) JOINT_MAP::iterator j; if( aLong ) + { for( j = m_joints.begin(); j != m_joints.end(); ++j ) { wxLogTrace( "PNS", "joint : %s, links : %d\n", - j->second.GetPos().Format().c_str(), j->second.LinkCount() ); + j->second.GetPos().Format().c_str(), j->second.LinkCount() ); JOINT::LINKED_ITEMS::const_iterator k; for( k = j->second.GetLinkList().begin(); k != j->second.GetLinkList().end(); ++k ) @@ -1187,7 +1190,7 @@ void NODE::Dump( bool aLong ) } } } - + } int lines_count = 0; diff --git a/pcbnew/router/pns_node.h b/pcbnew/router/pns_node.h index 02da9f067e..2c53ead1ba 100644 --- a/pcbnew/router/pns_node.h +++ b/pcbnew/router/pns_node.h @@ -3,7 +3,8 @@ * * Copyright (C) 2013-2014 CERN * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * + * @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 @@ -50,11 +51,9 @@ class ROUTER; class NODE; /** - * RULE_RESOLVER - * * An abstract function object, returning a design rule (clearance, diff pair gap, etc) required * between two items. - **/ + */ enum class CONSTRAINT_TYPE { @@ -97,28 +96,23 @@ public: virtual bool QueryConstraint( CONSTRAINT_TYPE aType, const PNS::ITEM* aItemA, const PNS::ITEM* aItemB, int aLayer, PNS::CONSTRAINT* aConstraint ) = 0; - + virtual wxString NetName( int aNet ) = 0; }; /** - * Struct OBSTACLE - * - * Holds an object colliding with another object, along with some useful data about the collision. - **/ + * Hold an object colliding with another object, along with some useful data about the collision. + */ struct OBSTACLE { - const ITEM* m_head; ///> Item we search collisions with + const ITEM* m_head; ///< Item we search collisions with - ITEM* m_item; ///> Item found to be colliding with m_head - SHAPE_LINE_CHAIN m_hull; ///> Hull of the colliding m_item - VECTOR2I m_ipFirst; ///> First intersection between m_head and m_hull - int m_distFirst; ///> ... and the distance thereof + ITEM* m_item; ///< Item found to be colliding with m_head + SHAPE_LINE_CHAIN m_hull; ///< Hull of the colliding m_item + VECTOR2I m_ipFirst; ///< First intersection between m_head and m_hull + int m_distFirst; ///< ... and the distance thereof }; -/** - * Struct OBSTACLE_VISITOR - **/ class OBSTACLE_VISITOR { public: @@ -136,23 +130,21 @@ protected: bool visit( ITEM* aCandidate ); protected: - const ITEM* m_item; ///> the item we are looking for collisions with + const ITEM* m_item; ///< the item we are looking for collisions with - const NODE* m_node; ///> node we are searching in (either root or a branch) - const NODE* m_override; ///> node that overrides root entries - int m_extraClearance; ///> additional clearance + const NODE* m_node; ///< node we are searching in (either root or a branch) + const NODE* m_override; ///< node that overrides root entries + int m_extraClearance; ///< additional clearance }; /** - * NODE + * Keep the router "world" - i.e. all the tracks, vias, solids in a hierarchical and indexed way. * - * Keeps the router "world" - i.e. all the tracks, vias, solids in a hierarchical and indexed way. * Features: - * - spatial-indexed container for PCB item shapes - * - collision search & clearance checking - * - assembly of lines connecting joints, finding loops and unique paths - * - lightweight cloning/branching (for recursive optimization and shove - * springback) + * - spatial-indexed container for PCB item shapes. + * - collision search & clearance checking. + * - assembly of lines connecting joints, finding loops and unique paths. + * - lightweight cloning/branching (for recursive optimization and shove springback). **/ class NODE { @@ -164,24 +156,24 @@ public: NODE(); ~NODE(); - ///> Returns the expected clearance between items a and b. + ///< Return the expected clearance between items a and b. int GetClearance( const ITEM* aA, const ITEM* aB ) const; int GetHoleClearance( const ITEM* aA, const ITEM* aB ) const; int GetHoleToHoleClearance( const ITEM* aA, const ITEM* aB ) const; - ///> Returns the pre-set worst case clearance between any pair of items + ///< Return the pre-set worst case clearance between any pair of items. int GetMaxClearance() const { return m_maxClearance; } - ///> Sets the worst-case clerance between any pair of items + ///< Set the worst-case clearance between any pair of items. void SetMaxClearance( int aClearance ) { m_maxClearance = aClearance; } - ///> Assigns a clerance resolution function object + ///< Assign a clearance resolution function object. void SetRuleResolver( RULE_RESOLVER* aFunc ) { m_ruleResolver = aFunc; @@ -192,93 +184,79 @@ public: return m_ruleResolver; } - ///> Returns the number of joints + ///< Return the number of joints. int JointCount() const { return m_joints.size(); } - ///> Returns the number of nodes in the inheritance chain (wrs to the root node) + ///< Return the number of nodes in the inheritance chain (wrs to the root node). int Depth() const { return m_depth; } /** - * Function QueryColliding() + * Find items colliding (closer than clearance) with the item \a aItem. * - * Finds items collliding (closer than clearance) with the item aItem. * @param aItem item to check collisions against * @param aObstacles set of colliding objects found * @param aKindMask mask of obstacle types to take into account * @param aLimitCount stop looking for collisions after finding this number of colliding items * @return number of obstacles found */ - int QueryColliding( const ITEM* aItem, - OBSTACLES& aObstacles, - int aKindMask = ITEM::ANY_T, - int aLimitCount = -1, - bool aDifferentNetsOnly = true ); + int QueryColliding( const ITEM* aItem, OBSTACLES& aObstacles, int aKindMask = ITEM::ANY_T, + int aLimitCount = -1, bool aDifferentNetsOnly = true ); - int QueryJoints( const BOX2I& aBox, - std::vector& aJoints, - LAYER_RANGE aLayerMask = LAYER_RANGE::All(), - int aKindMask = ITEM::ANY_T ); + int QueryJoints( const BOX2I& aBox, std::vector& aJoints, + LAYER_RANGE aLayerMask = LAYER_RANGE::All(), int aKindMask = ITEM::ANY_T ); /** - * Function NearestObstacle() - * - * Follows the line in search of an obstacle that is nearest to the starting to the line's + * Follow the line in search of an obstacle that is nearest to the starting to the line's * starting point. + * * @param aLine the item to find collisions with * @param aKindMask mask of obstacle types to take into account * @return the obstacle, if found, otherwise empty. */ - OPT_OBSTACLE NearestObstacle( const LINE* aLine, - int aKindMask = ITEM::ANY_T, - const std::set* aRestrictedSet = NULL ); + OPT_OBSTACLE NearestObstacle( const LINE* aLine, int aKindMask = ITEM::ANY_T, + const std::set* aRestrictedSet = NULL ); /** - * Function CheckColliding() - * - * Checks if the item collides with anything else in the world, and if found, returns the + * Check if the item collides with anything else in the world, and if found, returns the * obstacle. + * * @param aItem the item to find collisions with * @param aKindMask mask of obstacle types to take into account * @return the obstacle, if found, otherwise empty. */ - OPT_OBSTACLE CheckColliding( const ITEM* aItem, - int aKindMask = ITEM::ANY_T ); + OPT_OBSTACLE CheckColliding( const ITEM* aItem, int aKindMask = ITEM::ANY_T ); /** - * Function CheckColliding() - * - * Checks if any item in the set collides with anything else in the world, and if found, + * Check if any item in the set collides with anything else in the world, and if found, * returns the obstacle. - * @param aSet set of items to find collisions with - * @param aKindMask mask of obstacle types to take into account + * + * @param aSet set of items to find collisions with. + * @param aKindMask mask of obstacle types to take into account. * @return the obstacle, if found, otherwise empty. */ - OPT_OBSTACLE CheckColliding( const ITEM_SET& aSet, - int aKindMask = ITEM::ANY_T ); + OPT_OBSTACLE CheckColliding( const ITEM_SET& aSet, int aKindMask = ITEM::ANY_T ); /** - * Function HitTest() + * Find all items that contain the point \a aPoint. * - * Finds all items that contain the point aPoint. - * @param aPoint the point - * @return the items + * @param aPoint the point. + * @return the items. */ const ITEM_SET HitTest( const VECTOR2I& aPoint ) const; /** - * Function Add() + * Add an item to the current node. * - * Adds an item to the current node. - * @param aSegment item to add + * @param aSegment item to add. * @param aAllowRedundant if true, duplicate items are allowed (e.g. a segment or via - * at the same coordinates as an existing one) + * at the same coordinates as an existing one). * @return true if added */ bool Add( std::unique_ptr< SEGMENT > aSegment, bool aAllowRedundant = false ); @@ -288,14 +266,8 @@ public: void Add( LINE& aLine, bool aAllowRedundant = false ); -private: - void Add( std::unique_ptr< ITEM > aItem, bool aAllowRedundant = false ); - -public: /** - * Function Remove() - * - * Just as the name says, removes an item from this branch. + * Remove an item from this branch. */ void Remove( ARC* aArc ); void Remove( SOLID* aSolid ); @@ -303,19 +275,16 @@ public: void Remove( SEGMENT* aSegment ); void Remove( ITEM* aItem ); -public: /** - * Function Remove() + * Removes a line from this branch. * - * Just as the name says, removes a line from this branch. * @param aLine item to remove */ void Remove( LINE& aLine ); /** - * Function Replace() + * Replace an item with another one. * - * Just as the name says, replaces an item with another one. * @param aOldItem item to be removed * @param aNewItem item add instead */ @@ -323,78 +292,73 @@ public: void Replace( LINE& aOldLine, LINE& aNewLine ); /** - * Function Branch() + * Create a lightweight copy (called branch) of self that tracks the changes (added/removed + * items) wrs to the root. * - * Creates a lightweight copy (called branch) of self that tracks the changes (added/removed - * items) wrs to the root. Note that if there are any branches in use, their parents must NOT - * be deleted. - * @return the new branch + * @note If there are any branches in use, their parents must **not** be deleted. + * + * @return the new branch. */ NODE* Branch(); /** - * Function AssembleLine() + * Follow the joint map to assemble a line connecting two non-trivial joints starting from + * segment \a aSeg. * - * Follows the joint map to assemble a line connecting two non-trivial joints starting from - * segment aSeg. - * @param aSeg the initial segment - * @param aOriginSegmentIndex index of aSeg in the resulting line + * @param aSeg the initial segment. + * @param aOriginSegmentIndex index of aSeg in the resulting line. * @return the line */ const LINE AssembleLine( LINKED_ITEM* aSeg, int* aOriginSegmentIndex = NULL, - bool aStopAtLockedJoints = false ); + bool aStopAtLockedJoints = false ); - ///> Prints the contents and joints structure + ///< Print the contents and joints structure. void Dump( bool aLong = false ); /** - * Function GetUpdatedItems() + * Return the list of items removed and added in this branch with respect to the root branch. * - * Returns the list of items removed and added in this branch with respect to the root branch. - * @param aRemoved removed items - * @param aAdded added items + * @param aRemoved removed items. + * @param aAdded added items. */ void GetUpdatedItems( ITEM_VECTOR& aRemoved, ITEM_VECTOR& aAdded ); /** - * Function Commit() + * Apply the changes from a given branch (aNode) to the root branch. * - * Applies the changes from a given branch (aNode) to the root branch. Calling on a non-root - * branch will fail. Calling commit also kills all children nodes of the root branch. - * @param aNode node to commit changes from + * Calling on a non-root branch will fail. Calling commit also kills all children nodes of + * the root branch. + * + * @param aNode node to commit changes from. */ void Commit( NODE* aNode ); /** - * Function FindJoint() + * Search for a joint at a given position, layer and belonging to given net. * - * Searches for a joint at a given position, layer and belonging to given net. - * @return the joint, if found, otherwise empty + * @return the joint, if found, otherwise empty. */ JOINT* FindJoint( const VECTOR2I& aPos, int aLayer, int aNet ); void LockJoint( const VECTOR2I& aPos, const ITEM* aItem, bool aLock ); /** - * Function FindJoint() + * Search for a joint at a given position, linked to given item. * - * Searches for a joint at a given position, linked to given item. - * @return the joint, if found, otherwise empty + * @return the joint, if found, otherwise empty. */ JOINT* FindJoint( const VECTOR2I& aPos, const ITEM* aItem ) { return FindJoint( aPos, aItem->Layers().Start(), aItem->Net() ); } - ///> finds all lines between a pair of joints. Used by the loop removal procedure. - int FindLinesBetweenJoints( const JOINT& aA, - const JOINT& aB, - std::vector& aLines ); + ///< Find all lines between a pair of joints. Used by the loop removal procedure. + int FindLinesBetweenJoints( const JOINT& aA, const JOINT& aB, std::vector& aLines ); - ///> finds the joints corresponding to the ends of line aLine + ///< Find the joints corresponding to the ends of line \a aLine. void FindLineEnds( const LINE& aLine, JOINT& aA, JOINT& aB ); - ///> Destroys all child nodes. Applicable only to the root node. + ///< Destroy all child nodes. Applicable only to the root node. void KillChildren(); void AllItemsInNet( int aNet, std::set& aItems, int aKindMask = -1 ); @@ -415,33 +379,29 @@ public: return m_parent; } - ///> checks if this branch contains an updated version of the m_item from the root branch. + ///< Check if this branch contains an updated version of the m_item from the root branch. bool Overrides( ITEM* aItem ) const { return m_override.find( aItem ) != m_override.end(); } private: - struct DEFAULT_OBSTACLE_VISITOR; - typedef std::unordered_multimap JOINT_MAP; - typedef JOINT_MAP::value_type TagJointPair; + void Add( std::unique_ptr< ITEM > aItem, bool aAllowRedundant = false ); /// nodes are not copyable NODE( const NODE& aB ); NODE& operator=( const NODE& aB ); - ///> tries to find matching joint and creates a new one if not found - JOINT& touchJoint( const VECTOR2I& aPos, - const LAYER_RANGE& aLayers, - int aNet ); + ///< Try to find matching joint and creates a new one if not found. + JOINT& touchJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet ); - ///> touches a joint and links it to an m_item + ///< Touch a joint and links it to an m_item. void linkJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet, ITEM* aWhere ); - ///> unlinks an item from a joint + ///< Unlink an item from a joint. void unlinkJoint( const VECTOR2I& aPos, const LAYER_RANGE& aLayers, int aNet, ITEM* aWhere ); - ///> helpers for adding/removing items + ///< Helpers for adding/removing items. void addSolid( SOLID* aSeg ); void addSegment( SEGMENT* aSeg ); void addVia( VIA* aVia ); @@ -470,27 +430,31 @@ private: ARC* findRedundantArc( const VECTOR2I& A, const VECTOR2I& B, const LAYER_RANGE& lr, int aNet ); ARC* findRedundantArc( ARC* aSeg ); - ///> scans the joint map, forming a line starting from segment (current). + ///< Scan the joint map, forming a line starting from segment (current). void followLine( LINKED_ITEM* aCurrent, int aScanDirection, int& aPos, int aLimit, VECTOR2I* aCorners, LINKED_ITEM** aSegments, bool* aArcReversed, bool& aGuardHit, bool aStopAtLockedJoints ); private: - JOINT_MAP m_joints; ///> hash table with the joints, linking the items. Joints - ///> are hashed by their position, layer set and net. + struct DEFAULT_OBSTACLE_VISITOR; + typedef std::unordered_multimap JOINT_MAP; + typedef JOINT_MAP::value_type TagJointPair; - NODE* m_parent; ///> node this node was branched from - NODE* m_root; ///> root node of the whole hierarchy - std::set m_children; ///> list of nodes branched from this one + JOINT_MAP m_joints; ///< hash table with the joints, linking the items. Joints + ///< are hashed by their position, layer set and net. - std::unordered_set m_override; ///> hash of root's items that have been changed - ///> in this node + NODE* m_parent; ///< node this node was branched from + NODE* m_root; ///< root node of the whole hierarchy + std::set m_children; ///< list of nodes branched from this one - int m_maxClearance; ///> worst case item-item clearance - RULE_RESOLVER* m_ruleResolver; ///> Design rules resolver - INDEX* m_index; ///> Geometric/Net index of the items - int m_depth; ///> depth of the node (number of parent nodes in the - ///> inheritance chain) + std::unordered_set m_override; ///< hash of root's items that have been changed + ///< in this node + + int m_maxClearance; ///< worst case item-item clearance + RULE_RESOLVER* m_ruleResolver; ///< Design rules resolver + INDEX* m_index; ///< Geometric/Net index of the items + int m_depth; ///< depth of the node (number of parent nodes in the + ///< inheritance chain) std::unordered_set m_garbageItems; }; diff --git a/pcbnew/router/pns_optimizer.h b/pcbnew/router/pns_optimizer.h index 9d3585ceaa..689cf89c29 100644 --- a/pcbnew/router/pns_optimizer.h +++ b/pcbnew/router/pns_optimizer.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -39,12 +40,11 @@ class LINE; class DIFF_PAIR; class ITEM; class JOINT; +class OPT_CONSTRAINT; /** - * COST_ESTIMATOR - * - * Calculates the cost of a given line, taking corner angles and total length into account. - **/ + * Calculate the cost of a given line, taking corner angles and total length into account. + */ class COST_ESTIMATOR { public: @@ -79,19 +79,18 @@ private: int m_cornerCost; }; -class OPT_CONSTRAINT; /** - * OPTIMIZER + * Perform various optimizations of the lines being routed, attempting to make the lines shorter + * and less cornery. * - * Performs various optimizations of the lines being routed, attempting to make the lines shorter - * and less cornery. There are 3 kinds of optimizations so far: - * - Merging obtuse segments (MERGE_OBTUSE): tries to join together as many - * obtuse segments as possible without causing collisions - * - Rerouting path between pair of line corners with a 2-segment "\__" line and iteratively repeating - * the procedure as long as the total cost of the line keeps decreasing + * There are 3 kinds of optimizations so far: + * - Merging obtuse segments (MERGE_OBTUSE): tries to join together as many obtuse segments + * as possible without causing collisions. + * - Rerouting path between pair of line corners with a 2-segment "\__" line and iteratively + * repeating the procedure as long as the total cost of the line keeps decreasing. * - "Smart Pads" - that is, rerouting pad/via exits to make them look nice (SMART_PADS). - **/ + */ class OPTIMIZER { public: @@ -110,10 +109,10 @@ public: OPTIMIZER( NODE* aWorld ); ~OPTIMIZER(); - ///> a quick shortcut to optmize a line without creating and setting up an optimizer + ///< A quick shortcut to optimize a line without creating and setting up an optimizer. static bool Optimize( LINE* aLine, int aEffortLevel, NODE* aWorld, const VECTOR2I aV = VECTOR2I(0, 0) ); - + bool Optimize( LINE* aLine, LINE* aResult = NULL ); bool Optimize( DIFF_PAIR* aPair ); @@ -208,6 +207,7 @@ private: BOX2I m_restrictArea; }; + class OPT_CONSTRAINT { public: diff --git a/pcbnew/router/pns_routing_settings.h b/pcbnew/router/pns_routing_settings.h index 10182dbdac..dfcbeee766 100644 --- a/pcbnew/router/pns_routing_settings.h +++ b/pcbnew/router/pns_routing_settings.h @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2014 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * Copyright (C) 2016-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 @@ -33,16 +34,16 @@ class TOOL_SETTINGS; namespace PNS { -///> Routing modes +///< Routing modes enum PNS_MODE { - RM_MarkObstacles = 0, ///> Ignore collisions, mark obstacles - RM_Shove, ///> Only shove - RM_Walkaround, ///> Only walkaround - RM_Smart ///> Guess what's better, try to make least mess on the PCB + RM_MarkObstacles = 0, ///< Ignore collisions, mark obstacles + RM_Shove, ///< Only shove + RM_Walkaround, ///< Only walk around + RM_Smart ///< Guess what's better, try to make least mess on the PCB }; -///> Optimization effort +///< Optimization effort. enum PNS_OPTIMIZATION_EFFORT { OE_LOW = 0, @@ -50,7 +51,7 @@ enum PNS_OPTIMIZATION_EFFORT OE_FULL = 2 }; -///> What kind of corners to create in the line placers +///< What kind of corners to create in the line placers. enum class CORNER_MODE { MITERED_90, ///< H/V only (90-degree corners) (not yet implemented) @@ -60,9 +61,7 @@ enum class CORNER_MODE }; /** - * ROUTING_SETTINGS - * - * Contains all persistent settings of the router, such as the mode, optimization effort, etc. + * Contain all persistent settings of the router, such as the mode, optimization effort, etc. */ class ROUTING_SETTINGS : public NESTED_SETTINGS @@ -70,59 +69,62 @@ class ROUTING_SETTINGS : public NESTED_SETTINGS public: ROUTING_SETTINGS( JSON_SETTINGS* aParent, const std::string& aPath ); - ///> Returns the routing mode. + ///< Return the routing mode. PNS_MODE Mode() const { return m_routingMode; } - ///> Sets the routing mode. + ///< Set the routing mode. void SetMode( PNS_MODE aMode ) { m_routingMode = aMode; } - ///> Returns the optimizer effort. Bigger means cleaner traces, but slower routing. + ///< Return the optimizer effort. Bigger means cleaner traces, but slower routing. PNS_OPTIMIZATION_EFFORT OptimizerEffort() const { return m_optimizerEffort; } - ///> Sets the optimizer effort. Bigger means cleaner traces, but slower routing. + ///< Set the optimizer effort. Bigger means cleaner traces, but slower routing. void SetOptimizerEffort( PNS_OPTIMIZATION_EFFORT aEffort ) { m_optimizerEffort = aEffort; } - ///> Returns true if shoving vias is enbled. + ///< Return true if shoving vias is enabled. bool ShoveVias() const { return m_shoveVias; } - ///> Enables/disables shoving vias. + ///< Enable/disable shoving vias. void SetShoveVias( bool aShoveVias ) { m_shoveVias = aShoveVias; } - ///> Returns true if loop (redundant track) removal is on. + ///< Return true if loop (redundant track) removal is on. bool RemoveLoops() const { return m_removeLoops; } - ///> Enables/disables loop (redundant track) removal. + ///< Enable/disable loop (redundant track) removal. void SetRemoveLoops( bool aRemoveLoops ) { m_removeLoops = aRemoveLoops; } - ///> Returns true if suggesting the finish of currently placed track is on. + ///< Return true if suggesting the finish of currently placed track is on. bool SuggestFinish() { return m_suggestFinish; } - ///> Enables displaying suggestions for finishing the currently placed track. + ///< Enable displaying suggestions for finishing the currently placed track. void SetSuggestFinish( bool aSuggestFinish ) { m_suggestFinish = aSuggestFinish; } - ///> Returns true if Smart Pads (optimized connections) is enabled. + ///< Return true if Smart Pads (optimized connections) is enabled. bool SmartPads() const { return m_smartPads; } - ///> Enables/disables Smart Pads (optimized connections). + ///< Enable/disable Smart Pads (optimized connections). void SetSmartPads( bool aSmartPads ) { m_smartPads = aSmartPads; } - ///> Returns true if follow mouse mode is active (permanently on for the moment). + ///< Return true if follow mouse mode is active (permanently on for the moment). bool FollowMouse() const { return m_followMouse && !( Mode() == RM_MarkObstacles ); } - ///> Returns true if smoothing segments durign dragging is enabled. + ///< Return true if smoothing segments during dragging is enabled. bool SmoothDraggedSegments() const { return m_smoothDraggedSegments; } - ///> Enables/disabled smoothing segments during dragging. + ///< Enable/disable smoothing segments during dragging. void SetSmoothDraggedSegments( bool aSmooth ) { m_smoothDraggedSegments = aSmooth; } - ///> Returns true if jumping over unmovable obstacles is on. + ///< Return true if jumping over unmovable obstacles is on. bool JumpOverObstacles() const { return m_jumpOverObstacles; } - ///> Enables/disables jumping over unmovable obstacles. - void SetJumpOverObstacles( bool aJumpOverObstacles ) { m_jumpOverObstacles = aJumpOverObstacles; } + ///< Enable/disable jumping over unmovable obstacles. + void SetJumpOverObstacles( bool aJumpOverObstacles ) + { + m_jumpOverObstacles = aJumpOverObstacles; + } void SetStartDiagonal( bool aStartDiagonal ) { m_startDiagonal = aStartDiagonal; } diff --git a/pcbnew/router/router_tool.cpp b/pcbnew/router/router_tool.cpp index ac6cd5585c..2e521ac8e5 100644 --- a/pcbnew/router/router_tool.cpp +++ b/pcbnew/router/router_tool.cpp @@ -2,8 +2,9 @@ * KiRouter - a push-and-(sometimes-)shove PCB router * * Copyright (C) 2013-2017 CERN - * Copyright (C) 2017-2020 KiCad Developers, see AUTHORS.txt for contributors. - * Author: Tomasz Wlostowski + * 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 @@ -63,12 +64,12 @@ enum VIA_ACTION_FLAGS { // Via type VIA_MASK = 0x03, - VIA = 0x00, ///> Normal via - BLIND_VIA = 0x01, ///> blind/buried via - MICROVIA = 0x02, ///> Microvia + VIA = 0x00, ///< Normal via + BLIND_VIA = 0x01, ///< blind/buried via + MICROVIA = 0x02, ///< Microvia // Select layer - SELECT_LAYER = VIA_MASK + 1, ///> Ask user to select layer before adding via + SELECT_LAYER = VIA_MASK + 1, ///< Ask user to select layer before adding via }; @@ -502,6 +503,7 @@ void ROUTER_TOOL::handleCommonEvents( const TOOL_EVENT& aEvent ) for( auto evt : events) { wxString id = "null"; + if( evt.item && evt.item->Parent() ) id = evt.item->Parent()->m_Uuid.AsString(); @@ -972,7 +974,7 @@ bool ROUTER_TOOL::prepareInteractive() // It would make more sense to leave the net highlighted as the higher-contrast mode // makes the router clearances more visible. However, since we just started routing // the conversion of the screen from low contrast to high contrast is a bit jarring and - // makes the infobar coming up less noticable. + // makes the infobar coming up less noticeable. highlightNet( false ); frame()->ShowInfoBarError( m_router->FailureReason(), true, @@ -1562,7 +1564,7 @@ int ROUTER_TOOL::InlineDrag( const TOOL_EVENT& aEvent ) // We tweak the mouse position using the value from above, and then use that as the // start position to prevent the footprint from jumping when we start dragging. - // First we move the visual crosshair cursor... + // First we move the visual cross hair cursor... controls()->ForceCursorPosition( true, tweakedMousePos ); controls()->SetCursorPosition( tweakedMousePos ); // ...then the mouse pointer @@ -1713,7 +1715,8 @@ int ROUTER_TOOL::InlineBreakTrack( const TOOL_EVENT& aEvent ) if( selection.Size() != 1 ) return 0; - const BOARD_CONNECTED_ITEM* item = static_cast( selection.Front() ); + const BOARD_CONNECTED_ITEM* item = + static_cast( selection.Front() ); if( item->Type() != PCB_TRACE_T ) return 0; diff --git a/pcbnew/tools/board_editor_control.h b/pcbnew/tools/board_editor_control.h index 92189d4bc8..40e5eba53b 100644 --- a/pcbnew/tools/board_editor_control.h +++ b/pcbnew/tools/board_editor_control.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -35,9 +37,7 @@ namespace KIGFX { class PCB_EDIT_FRAME; /** - * BOARD_EDITOR_CONTROL - * - * Handles actions specific to the board editor in pcbnew. + * Handle actions specific to the board editor in PcbNew. */ class BOARD_EDITOR_CONTROL : public PCB_TOOL_BASE { @@ -83,56 +83,53 @@ public: // Zone actions int ZoneMerge( const TOOL_EVENT& aEvent ); - ///> Duplicates a zone onto a layer (prompts for new layer) + ///< Duplicate a zone onto a layer (prompts for new layer) int ZoneDuplicate( const TOOL_EVENT& aEvent ); int EditFpInFpEditor( const TOOL_EVENT& aEvent ); /** - * Function PlaceTarget() - * Allows user to place a layer alignment target. + * Allow user to place a layer alignment target. */ int PlaceTarget( const TOOL_EVENT& aEvent ); /** - * Function PlaceFootprint() - * Displays a dialog to select a footprint to be added and allows the user to set its position. + * Display a dialog to select a footprint to be added and allows the user to set its position. */ int PlaceFootprint( const TOOL_EVENT& aEvent ); - ///> Toggles 'lock' property for selected items. + ///< Toggle 'lock' property for selected items. int ToggleLockSelected( const TOOL_EVENT& aEvent ); - ///> Locks selected items. + ///< Lock selected items. int LockSelected( const TOOL_EVENT& aEvent ); - ///> Unlocks selected items. + ///< Unlock selected items. int UnlockSelected( const TOOL_EVENT& aEvent ); - ///> Runs the drill origin tool for setting the origin for drill and pick-and-place files. + ///< Run the drill origin tool for setting the origin for drill and pick-and-place files. int DrillOrigin( const TOOL_EVENT& aEvent ); - ///> Low-level access (below undo) to setting the drill origin + ///< Low-level access (below undo) to setting the drill origin. static void DoSetDrillOrigin( KIGFX::VIEW* aView, PCB_BASE_FRAME* aFrame, EDA_ITEM* aItem, const VECTOR2D& aPoint ); int FlipPcbView( const TOOL_EVENT& aEvent ); private: - ///> How to modify a property for selected items. + ///< How to modify a property for selected items. enum MODIFY_MODE { ON, OFF, TOGGLE }; int modifyLockSelected( MODIFY_MODE aMode ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; -private: - PCB_EDIT_FRAME* m_frame; ///> Pointer to the currently used edit frame. + PCB_EDIT_FRAME* m_frame; ///< Pointer to the currently used edit frame. - std::unique_ptr m_placeOrigin; ///> Place & drill origin marker + std::unique_ptr m_placeOrigin; ///< Place & drill origin marker - static const int WIDTH_STEP; ///> How does line width change after one -/+ key press. + static const int WIDTH_STEP; ///< How does line width change after one -/+ key press. }; #endif diff --git a/pcbnew/tools/board_inspection_tool.h b/pcbnew/tools/board_inspection_tool.h index e08d97bc74..0e6450ff63 100644 --- a/pcbnew/tools/board_inspection_tool.h +++ b/pcbnew/tools/board_inspection_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -51,8 +51,6 @@ protected: /** - * BOARD_INSPECTION_TOOL - * * Tool for pcb inspection. */ class BOARD_INSPECTION_TOOL : public wxEvtHandler, public PCB_TOOL_BASE @@ -67,63 +65,61 @@ public: void Reset( RESET_REASON aReason ) override; /** - * Function ShowStatisticDialog() - * - * Shows dialog with board statistics + * Show dialog with board statistics. */ int ShowStatisticsDialog( const TOOL_EVENT& aEvent ); - ///> Notifies eeschema about the selected item. + ///< Notify Eeschema about the selected item. int CrossProbePcbToSch( const TOOL_EVENT& aEvent ); - ///> Highlights net belonging to the item under the cursor. + ///< Highlight net belonging to the item under the cursor. int HighlightNet( const TOOL_EVENT& aEvent ); - ///> Clears all board highlights + ///< Clear all board highlights int ClearHighlight( const TOOL_EVENT& aEvent ); - ///> Launches a tool to pick the item whose net is going to be highlighted. + ///< Launch a tool to pick the item whose net is going to be highlighted. int HighlightNetTool( const TOOL_EVENT& aEvent ); - ///> Performs the appropriate action in response to an eeschema cross-probe. + ///< Perform the appropriate action in response to an Eeschema cross-probe. int HighlightItem( const TOOL_EVENT& aEvent ); - ///> Updates ratsnest for selected items. + ///< Update ratsnest for selected items. int UpdateSelectionRatsnest( const TOOL_EVENT& aEvent ); - ///> Hides ratsnest for selected items. Called when there are no items selected. + ///< Hide ratsnest for selected items. Called when there are no items selected. int HideDynamicRatsnest( const TOOL_EVENT& aEvent ); - ///> Shows local ratsnest of a component + ///< Show local ratsnest of a component. int LocalRatsnestTool( const TOOL_EVENT& aEvent ); int FlipPcbView( const TOOL_EVENT& aEvent ); int ListNets( const TOOL_EVENT& aEvent ); - ///> Hide the ratsnest for a given net + ///< Hide the ratsnest for a given net. int HideNet( const TOOL_EVENT& aEvent ); - ///> Show the ratsnest for a given net + ///< Show the ratsnest for a given net. int ShowNet( const TOOL_EVENT& aEvent ); - ///> Show the clearance resolution for two selected items + ///< Show the clearance resolution for two selected items. int InspectClearance( const TOOL_EVENT& aEvent ); int InspectConstraints( const TOOL_EVENT& aEvent ); private: - ///> Event handler to recalculate dynamic ratsnest + ///< Event handler to recalculate dynamic ratsnest. void ratsnestTimer( wxTimerEvent& aEvent ); - ///> Recalculates dynamic ratsnest for the current selection + ///< Recalculate dynamic ratsnest for the current selection. void calculateSelectionRatsnest( const VECTOR2I& aDelta ); bool highlightNet( const VECTOR2D& aPosition, bool aUseSelection ); void doHideNet( int aNetCode, bool aHide ); - ///> Bind handlers to corresponding TOOL_ACTIONs + ///< Bind handlers to corresponding TOOL_ACTIONs. void setTransitions() override; void onListNetsDialogClosed( wxCommandEvent& aEvent ); @@ -140,7 +136,7 @@ private: private: PCB_EDIT_FRAME* m_frame; // Pointer to the currently used edit frame. - bool m_probingSchToPcb; // Recursion guard when cross-probing to EESchema + bool m_probingSchToPcb; // Recursion guard when cross-probing to Eeschema int m_lastNetcode; // Used for toggling between last two highlighted nets CONNECTIVITY_DATA* m_dynamicData; // Cached connectivity data from the selection diff --git a/pcbnew/tools/convert_tool.h b/pcbnew/tools/convert_tool.h index 4bc5054244..4db1588b8b 100644 --- a/pcbnew/tools/convert_tool.h +++ b/pcbnew/tools/convert_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Jon Evans * * This program is free software; you can redistribute it and/or @@ -46,53 +46,57 @@ public: bool Init() override; /** - * Converts selected lines to a polygon, if possible + * Convert selected lines to a polygon, if possible. */ int LinesToPoly( const TOOL_EVENT& aEvent ); /** - * Converts selected polygon-like object to graphic lines, if possible + * Convert selected polygon-like object to graphic lines, if possible. */ int PolyToLines( const TOOL_EVENT& aEvent ); /** - * Converts selected segment (graphic or track) to an arc of the same type + * Convert selected segment (graphic or track) to an arc of the same type */ int SegmentToArc( const TOOL_EVENT& aEvent ); - ///> @copydoc TOOL_INTERACTIVE::setTransitions() + ///< @copydoc TOOL_INTERACTIVE::setTransitions() void setTransitions() override; private: - /** - * Retrieves the start and end points for a generic item - * @param aItem is an item that has a start and end point - * @return a segment from start to end, or NULLOPT if invalid + * Retrieve the start and end points for a generic item. + * + * @param aItem is an item that has a start and end point. + * @return a segment from start to end, or NULLOPT if invalid. */ static OPT getStartEndPoints( EDA_ITEM* aItem ); /** - * Tries to make polygons from segments in the selected items. + * Try to make polygons from segments in the selected items. + * * Polygons are formed from chains of lines/arcs. Each set containing two or more lines/arcs - * that are connected will be added to the return SHAPE_POLY_SET as an outline. - * No attempt is made to guess at holes. - * @param aItems is a list of items to process - * @return a SHAPE_POLY_SET containing any polygons that were created + * that are connected will be added to the return SHAPE_POLY_SET as an outline. No attempt + * is made to guess at holes. + * + * @param aItems is a list of items to process. + * @return a #SHAPE_POLY_SET containing any polygons that were created. */ static SHAPE_POLY_SET makePolysFromSegs( const std::deque& aItems ); /** - * Tries to make polygons from rects - * @param aItems is a list of rect shapes to process - * @return a SHAPE_POLY_SET containing any polygons that were created + * Try to make polygons from rectangles. + * + * @param aItems is a list of rect shapes to process. + * @return a #SHAPE_POLY_SET containing any polygons that were created. */ static SHAPE_POLY_SET makePolysFromRects( const std::deque& aItems ); /** - * Tries to make polygons from circles - * @param aItems is a list of circle shapes to process - * @return a SHAPE_POLY_SET containing any polygons that were created + * Try to make polygons from circles. + * + * @param aItems is a list of circle shapes to process. + * @return a #SHAPE_POLY_SET containing any polygons that were created. */ static SHAPE_POLY_SET makePolysFromCircles( const std::deque& aItems ); diff --git a/pcbnew/tools/drawing_tool.h b/pcbnew/tools/drawing_tool.h index 113b9aaa2d..6b0daac4f5 100644 --- a/pcbnew/tools/drawing_tool.h +++ b/pcbnew/tools/drawing_tool.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014-2017 CERN - * Copyright (C) 2018-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2018-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -36,14 +37,13 @@ namespace KIGFX class VIEW; class VIEW_CONTROLS; } + class BOARD; class PCB_BASE_EDIT_FRAME; class PCB_SHAPE; class POLYGON_GEOM_MANAGER; /** - * DRAWING_TOOL - * * Tool responsible for drawing graphical elements like lines, arcs, circles, etc. */ @@ -59,7 +59,7 @@ public: /// @copydoc TOOL_INTERACTIVE::Reset() void Reset( RESET_REASON aReason ) override; - ///> The possible drawing modes of DRAWING_TOOL + ///< The possible drawing modes of DRAWING_TOOL enum class MODE { NONE, @@ -78,149 +78,147 @@ public: }; /** - * Function GetDrawingMode - * - * Returns the current drawing mode of the DRAWING_TOOL, or - * MODE::NONE if not currently in any drawing mode + * Return the current drawing mode of the DRAWING_TOOL or #MODE::NONE if not currently in + * any drawing mode. */ MODE GetDrawingMode() const; /** - * Function DrawLine() - * Starts interactively drawing a line. After invoking the function it expects the user - * to click at least two times to determine the origin and the end for a line. If there are - * more clicks, the line is drawn as a continous polyline. + * Start interactively drawing a line. + * + * After invoking the function it expects the user to click at least two times to determine + * the origin and the end for a line. If there are more clicks, the line is drawn as a + * continuous polyline. */ int DrawLine( const TOOL_EVENT& aEvent ); /** - * Function DrawRectangle() - * Starts interactively drawing a rectangle. After invoking the function it expects the user - * to first click on a point that is going to be used as the top-left of the rectangle. The - * second click determines the bottom-right. + * Start interactively drawing a rectangle. + * + * After invoking the function it expects the user to first click on a point that is going + * to be used as the top-left of the rectangle. The second click determines the bottom-right. */ int DrawRectangle( const TOOL_EVENT& aEvent ); /** - * Function DrawCircle() - * Starts interactively drawing a circle. After invoking the function it expects the user - * to first click on a point that is going to be used as the center of the circle. The second - * click determines the circle radius. + * Start interactively drawing a circle. + * + * After invoking the function it expects the user to first click on a point that is going + * to be used as the center of the circle. The second click determines the circle radius. */ int DrawCircle( const TOOL_EVENT& aEvent ); /** - * Function DrawArc() - * Starts interactively drawing an arc. After invoking the function it expects the user - * to first click on a point that is going to be used as the center of the arc. The second - * click determines the origin and radius, the third one - the angle. + * Start interactively drawing an arc. + * + * After invoking the function it expects the user to first click on a point that is going + * to be used as the center of the arc. The second click determines the origin and radius, + * the third one - the angle. */ int DrawArc( const TOOL_EVENT& aEvent ); /** - * Function PlaceText() - * Displays a dialog that allows one to input text and its settings and then - * lets the user decide where to place the text in editor. + * Display a dialog that allows one to input text and its settings and then lets the user + * decide where to place the text in editor. */ int PlaceText( const TOOL_EVENT& aEvent ); /** - * Function DrawDimension() - * Starts interactively drawing a dimension. After invoking the function it expects the user - * to first click on a point that is going to be used as the origin of the dimension. - * The second click determines the end and the third click modifies its height. + * Start interactively drawing a dimension. + * + * After invoking the function it expects the user to first click on a point that is going + * to be used as the origin of the dimension. The second click determines the end and the + * third click modifies its height. */ int DrawDimension( const TOOL_EVENT& aEvent ); /** - * Function DrawZone() - * Starts interactively drawing a zone. After invoking the function a zone settings dialog - * is displayed. After confirmation it allows the user to set points that are going to be used - * as a boundary polygon of the zone. Double click or clicking on the origin of the boundary - * polyline finishes the drawing. + * Start interactively drawing a zone. + * + * After invoking the function a zone settings dialog is displayed. After confirmation it + * allows the user to set points that are going to be used as a boundary polygon of the + * zone. Double click or clicking on the origin of the boundary polyline finishes the + * drawing. * * The event parameter indicates which type of zone to draw: - * ADD add a new zone/keepout with fresh settings - * CUTOUT add a cutout to an existing zone - * SIMILAR add a new zone with the same settings as an existing one + * - ADD add a new zone/keepout with fresh settings. + * - CUTOUT add a cutout to an existing zone. + * - SIMILAR add a new zone with the same settings as an existing one. */ int DrawZone( const TOOL_EVENT& aEvent ); int DrawVia( const TOOL_EVENT& aEvent ); /** - * Function PlaceImportedGraphics() - * Places a drawing imported from a DXF or SVG file in footprint editor. + * Place a drawing imported from a DXF or SVG file in footprint editor. */ int PlaceImportedGraphics( const TOOL_EVENT& aEvent ); /** - * Function SetAnchor() - * Places the footprint anchor (only in footprint editor). + * Place the footprint anchor (only in footprint editor). */ int SetAnchor( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: - /** - * Starts drawing a selected shape (i.e. PCB_SHAPE). + * Start drawing a selected shape (i.e. PCB_SHAPE). + * * @param aGraphic is an object that is going to be used by the tool for drawing. Must be * already created. The tool deletes the object if it is not added to a BOARD. * @param aStartingPoint is a starting point for this new PCB_SHAPE. If it exists the new * item has its start point set to aStartingPoint, and its settings * (width, layer) set to the current default values. - * @return False if the tool was cancelled before the origin was set or origin and end are + * @return False if the tool was canceled before the origin was set or origin and end are * the same point. */ bool drawSegment( const std::string& aTool, PCB_SHAPE** aGraphic, OPT aStartingPoint ); /** - * Starts drawing an arc. + * Start drawing an arc. + * * @param aGraphic is an object that is going to be used by the tool for drawing. Must be * already created. The tool deletes the object if it is not added to a BOARD. - * @return False if the tool was cancelled before the origin was set or origin and end are + * @return False if the tool was canceled before the origin was set or origin and end are * the same point. */ bool drawArc( const std::string& aTool, PCB_SHAPE** aGraphic, bool aImmediateMode ); /** - * Draws a polygon, that is added as a zone or a keepout area. + * Draw a polygon, that is added as a zone or a keepout area. * - * @param aKeepout dictates if the drawn polygon is a zone or a - * keepout area. + * @param aKeepout dictates if the drawn polygon is a zone or a keepout area. * @param aMode dictates the mode of the zone tool: - * ADD add a new zone/keepout with fresh settings - * CUTOUT add a cutout to an existing zone - * SIMILAR add a new zone with the same settings as an existing one + * - ADD add a new zone/keepout with fresh settings + * - CUTOUT add a cutout to an existing zone + * - SIMILAR add a new zone with the same settings as an existing one */ /** - * Function getSourceZoneForAction() + * Get a source zone item for an action that takes an existing zone into account (for + * example a cutout of an existing zone). * - * Gets a source zone item for an action that takes an existing zone - * into account (for example a cutout of an existing zone). The source - * zone is taken from the current selection + * The source zone is taken from the current selection. * * @param aMode mode of the zone tool - * @param aZone updated pointer to a suitable source zone, - * or nullptr if none found, or the action doesn't need a source - * @return true if a suitable zone was found, or the action doesn't - * need a zone. False if the action needs a zone but none was found. + * @param aZone updated pointer to a suitable source zone, or nullptr if none found, or + * the action doesn't need a source + * @return true if a suitable zone was found, or the action doesn't need a zone. False if + * the action needs a zone but none was found. */ bool getSourceZoneForAction( ZONE_MODE aMode, ZONE** aZone ); /** - * Function constrainDimension() - * Forces the dimension lime to be drawn on multiple of 45 degrees - * @param aDimension is the dimension element currently being drawn + * Force the dimension lime to be drawn on multiple of 45 degrees. + * + * @param aDimension is the dimension element currently being drawn. */ void constrainDimension( DIMENSION_BASE* aDim ); - ///> Returns the appropriate width for a segment depending on the settings. + ///< Return the appropriate width for a segment depending on the settings. int getSegmentWidth( PCB_LAYER_ID aLayer ) const; KIGFX::VIEW* m_view; diff --git a/pcbnew/tools/drc_tool.h b/pcbnew/tools/drc_tool.h index c621dea9d4..a23932ed6c 100644 --- a/pcbnew/tools/drc_tool.h +++ b/pcbnew/tools/drc_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -51,29 +51,6 @@ public: /// @copydoc TOOL_INTERACTIVE::Reset() void Reset( RESET_REASON aReason ) override; -private: - PCB_EDIT_FRAME* m_editFrame; // The pcb frame editor which owns the board - BOARD* m_pcb; - DIALOG_DRC* m_drcDialog; - bool m_drcRunning; - - std::shared_ptr m_drcEngine; - - std::vector> m_unconnected; // list of unconnected pads - std::vector> m_footprints; // list of footprint warnings - -private: - ///> Sets up handlers for various events. - void setTransitions() override; - - /** - * Update needed pointers from the one pointer which is known not to change. - */ - void updatePointers(); - - EDA_UNITS userUnits() const { return m_editFrame->GetUserUnits(); } - -public: /** * Open a dialog and prompts the user, then if a test run button is * clicked, runs the test(s) and creates the MARKERS. The dialog is only @@ -106,7 +83,7 @@ public: bool IsDRCRunning() const { return m_drcRunning; } /** - * Closes and frees the DRC dialog. + * Close and free the DRC dialog. */ void DestroyDRCDialog(); @@ -121,6 +98,27 @@ public: int PrevMarker( const TOOL_EVENT& aEvent ); int NextMarker( const TOOL_EVENT& aEvent ); int ExcludeMarker( const TOOL_EVENT& aEvent ); + +private: + ///< Set up handlers for various events. + void setTransitions() override; + + /** + * Update needed pointers from the one pointer which is known not to change. + */ + void updatePointers(); + + EDA_UNITS userUnits() const { return m_editFrame->GetUserUnits(); } + + PCB_EDIT_FRAME* m_editFrame; // The pcb frame editor which owns the board + BOARD* m_pcb; + DIALOG_DRC* m_drcDialog; + bool m_drcRunning; + + std::shared_ptr m_drcEngine; + + std::vector> m_unconnected; // list of unconnected pads + std::vector> m_footprints; // list of footprint warnings }; diff --git a/pcbnew/tools/edit_tool.h b/pcbnew/tools/edit_tool.h index d081c944b9..d6fe92bb7e 100644 --- a/pcbnew/tools/edit_tool.h +++ b/pcbnew/tools/edit_tool.h @@ -3,6 +3,7 @@ * * Copyright (C) 2013-2020 CERN * Copyright (C) 2013-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * @author Tomasz Wlostowski * @@ -54,10 +55,10 @@ public: }; /** - * EDIT_TOOL + * The interactive edit tool. * - * The interactive edit tool. Allows one to move, rotate, flip and change properties of items s - * elected using the pcbnew.InteractiveSelection tool. + * Allows one to move, rotate, flip and change properties of items selected using the + * pcbnew.InteractiveSelection tool. */ class EDIT_TOOL : public PCB_TOOL_BASE @@ -71,99 +72,85 @@ public: /// @copydoc TOOL_INTERACTIVE::Init() bool Init() override; - ///> Find an item and start moving. + ///< Find an item and start moving. int GetAndPlace( const TOOL_EVENT& aEvent ); /** - * Function Move() * Main loop in which events are handled. */ int Move( const TOOL_EVENT& aEvent ); /** - * Function Drag() * Invoke the PNS router to drag tracks or do an offline resizing of an arc track - * if a single arc track is selected + * if a single arc track is selected. */ int Drag( const TOOL_EVENT& aEvent ); /** - * Function DragArcTrack() - * Drag-resize an arc (and change end points of connected straight segments) + * Drag-resize an arc (and change end points of connected straight segments). */ int DragArcTrack( const TOOL_EVENT& aEvent ); /** - * Function Properties() - * Displays properties window for the selected object. + * Display properties window for the selected object. */ int Properties( const TOOL_EVENT& aEvent ); /** - * Function Rotate() - * Rotates currently selected items. + * Rotate currently selected items. */ int Rotate( const TOOL_EVENT& aEvent ); /** - * Function Flip() - * Rotates currently selected items. The rotation point is the current cursor position. + * Rotate currently selected items. The rotation point is the current cursor position. */ int Flip( const TOOL_EVENT& aEvent ); /** - * Function Mirror - * Mirrors the current selection. The mirror axis passes through the current point. + * Mirror the current selection. The mirror axis passes through the current point. */ int Mirror( const TOOL_EVENT& aEvent ); int ChangeTrackWidth( const TOOL_EVENT& aEvent ); /** - * Function FilletTracks() - * Fillets (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius + * Fillet (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius. */ int FilletTracks( const TOOL_EVENT& aEvent ); /** - * Function Remove() - * Deletes currently selected items. The rotation point is the current cursor position. + * Delete currently selected items. */ int Remove( const TOOL_EVENT& aEvent ); /** - * Function Duplicate() - * Duplicates the current selection and starts a move action. + * Duplicate the current selection and starts a move action. */ int Duplicate( const TOOL_EVENT& aEvent ); /** - * Function MoveExact() - * Invokes a dialog box to allow moving of the item by an exact amount. + * Invoke a dialog box to allow moving of the item by an exact amount. */ int MoveExact( const TOOL_EVENT& aEvent ); /** - * Moves an item but with a reference point selected first + * Move an item but with a reference point selected first */ int MoveWithReference( const TOOL_EVENT& aEvent ); /** - * Function CreateArray() - * Creates an array of the selected items, invoking the array editor dialog to set the options. + * Create an array of the selected items, invoking the array editor dialog to set the options. */ int CreateArray( const TOOL_EVENT& aEvent ); /** - * Function FootprintFilter() - * A selection filter which prunes the selection to contain only items of type PCB_MODULE_T + * A selection filter which prunes the selection to contain only items of type #PCB_MODULE_T. */ static void FootprintFilter( const VECTOR2I&, GENERAL_COLLECTOR& aCollector, PCB_SELECTION_TOOL* sTool ); /** - * Function PadFilter() - * A selection filter which prunes the selection to contain only items of type PCB_PAD_T + * A selection filter which prunes the selection to contain only items of type #PCB_PAD_T. */ static void PadFilter( const VECTOR2I&, GENERAL_COLLECTOR& aCollector, PCB_SELECTION_TOOL* sTool ); @@ -171,25 +158,23 @@ public: BOARD_COMMIT* GetCurrentCommit() const { return m_commit.get(); } private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; /** - * Function copyToClipboard() - * Sends the current selection to the clipboard by formatting it as a fake pcb - * see AppendBoardFromClipboard for importing + * Send the current selection to the clipboard by formatting it as a fake pcb + * see #AppendBoardFromClipboard for importing. */ int copyToClipboard( const TOOL_EVENT& aEvent ); /** - * Function cutToClipboard() - * Cuts the current selection to the clipboard by formatting it as a fake pcb - * see AppendBoardFromClipboard for importing + * Cut the current selection to the clipboard by formatting it as a fake pcb + * see #AppendBoardFromClipboard for importing. */ int cutToClipboard( const TOOL_EVENT& aEvent ); - ///> Returns the right modification point (e.g. for rotation), depending on the number of - ///> selected items. + ///< Return the right modification point (e.g. for rotation), depending on the number of + ///< selected items. bool updateModificationPoint( PCB_SELECTION& aSelection ); bool invokeInlineRouter( int aDragMode ); diff --git a/pcbnew/tools/footprint_editor_control.h b/pcbnew/tools/footprint_editor_control.h index 4da28546e1..db9b443cd6 100644 --- a/pcbnew/tools/footprint_editor_control.h +++ b/pcbnew/tools/footprint_editor_control.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -32,8 +34,6 @@ class FOOTPRINT_EDIT_FRAME; class DIALOG_FOOTPRINT_CHECKER; /** - * FOOTPRINT_EDITOR_CONTROL - * * Module editor specific tools. */ class FOOTPRINT_EDITOR_CONTROL : public PCB_TOOL_BASE @@ -50,7 +50,7 @@ public: int NewFootprint( const TOOL_EVENT& aEvent ); int CreateFootprint( const TOOL_EVENT& aEvent ); - + int Save( const TOOL_EVENT& aEvent ); int SaveAs( const TOOL_EVENT& aEvent ); int Revert( const TOOL_EVENT& aEvent ); @@ -78,10 +78,9 @@ public: int DefaultPadProperties( const TOOL_EVENT& aEvent ); private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; -private: FOOTPRINT_EDIT_FRAME* m_frame; DIALOG_FOOTPRINT_CHECKER* m_checkerDialog; diff --git a/pcbnew/tools/global_edit_tool.h b/pcbnew/tools/global_edit_tool.h index 5ede94f0f2..6babfcf7f7 100644 --- a/pcbnew/tools/global_edit_tool.h +++ b/pcbnew/tools/global_edit_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see AUTHORS.TXT for contributors. + * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -47,10 +47,10 @@ public: bool Init() override; /** - * Function ExchangeFootprints() - * * Invoke the dialog used to update or exchange the footprint definitions used for - * footprints. The mode depends on the PCB_ACTIONS held by the TOOL_EVENT. + * footprints. + * + * The mode depends on the #PCB_ACTIONS held by the #TOOL_EVENT. */ int ExchangeFootprints( const TOOL_EVENT& aEvent ); @@ -66,7 +66,7 @@ public: private: bool swapBoardItem( BOARD_ITEM* aItem, PCB_LAYER_ID* aLayerMap ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: diff --git a/pcbnew/tools/group_tool.h b/pcbnew/tools/group_tool.h index 4d61b1bfe6..22bca6c08e 100644 --- a/pcbnew/tools/group_tool.h +++ b/pcbnew/tools/group_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -47,32 +47,29 @@ public: int GroupProperties( const TOOL_EVENT& aEvent ); /** - * Function SelectNewMember() - * - * Invokes the picker tool to select a new member of the group. + * Invoke the picker tool to select a new member of the group. */ int PickNewMember( const TOOL_EVENT& aEvent ); - ///> Groups selected items. + ///< Group selected items. int Group( const TOOL_EVENT& aEvent ); - ///> Ungroups selected items. + ///< Ungroup selected items. int Ungroup( const TOOL_EVENT& aEvent ); - ///> Remove selection from group. + ///< Remove selection from group. int RemoveFromGroup( const TOOL_EVENT& aEvent ); - ///> Restrict seletion to only member of the group. + ///< Restrict selection to only member of the group. int EnterGroup( const TOOL_EVENT& aEvent ); - ///> Leave the current group (deselect its members and select the group as a whole) + ///< Leave the current group (deselect its members and select the group as a whole). int LeaveGroup( const TOOL_EVENT& aEvent ); private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; -private: PCB_BASE_EDIT_FRAME* m_frame; DIALOG_GROUP_PROPERTIES* m_propertiesDialog; PCB_SELECTION_TOOL* m_selectionTool; diff --git a/pcbnew/tools/pad_tool.h b/pcbnew/tools/pad_tool.h index 614e761b70..eda0f965fc 100644 --- a/pcbnew/tools/pad_tool.h +++ b/pcbnew/tools/pad_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -30,9 +30,7 @@ class ACTION_MENU; /** - * PAD_TOOL - * - * Tools relating to pads and pad settings + * Tool relating to pads and pad settings. */ class PAD_TOOL : public PCB_TOOL_BASE { @@ -40,26 +38,24 @@ public: PAD_TOOL(); ~PAD_TOOL(); - ///> React to model/view changes + ///< React to model/view changes void Reset( RESET_REASON aReason ) override; - ///> Basic initalization + ///< Basic initialization bool Init() override; /** - * Function EnumeratePads() * Tool for quick pad enumeration. */ int EnumeratePads( const TOOL_EVENT& aEvent ); /** - * Function PlacePad() - * Places a pad in footprint editor. + * Place a pad in footprint editor. */ int PlacePad( const TOOL_EVENT& aEvent ); /** - * Enters/exits WYSIWYG pad shape editing + * Enter/exit WYSIWYG pad shape editing. */ int EditPad( const TOOL_EVENT& aEvent ); @@ -67,22 +63,21 @@ public: void SetLastPadName( const wxString& aPadName ) { m_lastPadName = aPadName; } private: - ///> Bind handlers to corresponding TOOL_ACTIONs + ///< Bind handlers to corresponding TOOL_ACTIONs. void setTransitions() override; - ///> Apply pad settings from board design settings to a pad + ///< Apply pad settings from board design settings to a pad. int pastePadProperties( const TOOL_EVENT& aEvent ); - ///> Copy pad settings from a pad to the board design settings + ///< Copy pad settings from a pad to the board design settings. int copyPadSettings( const TOOL_EVENT& aEvent ); - ///> Push pad settings from a pad to other pads on board or footprint + ///< Push pad settings from a pad to other pads on board or footprint. int pushPadSettings( const TOOL_EVENT& aEvent ); PCB_LAYER_ID explodePad( PAD* aPad ); void recombinePad( PAD* aPad ); -private: wxString m_lastPadName; bool m_padCopied; // Indicates there are valid settings in the Master Pad object diff --git a/pcbnew/tools/pcb_actions.h b/pcbnew/tools/pcb_actions.h index 81219b93aa..44d43a5804 100644 --- a/pcbnew/tools/pcb_actions.h +++ b/pcbnew/tools/pcb_actions.h @@ -2,7 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -43,10 +44,10 @@ enum class ZONE_MODE /** - * PCB_ACTIONS + * Gather all the actions that are shared by tools. * - * Gathers all the actions that are shared by tools. The instance of PCB_ACTIONS is created - * inside of ACTION_MANAGER object that registers the actions. + * The instance of PCB_ACTIONS is created inside of #ACTION_MANAGER object that registers + * the actions. */ class PCB_ACTIONS : public ACTIONS { @@ -58,37 +59,37 @@ public: /// Select a single item under the cursor position static TOOL_ACTION selectionCursor; - /// Clears the current selection + /// Clear the current selection static TOOL_ACTION selectionClear; - /// Selects an item (specified as the event parameter). + /// Select an item (specified as the event parameter). static TOOL_ACTION selectItem; static TOOL_ACTION unselectItem; - /// Selects a list of items (specified as the event parameter) + /// Select a list of items (specified as the event parameter) static TOOL_ACTION selectItems; static TOOL_ACTION unselectItems; - /// Runs a selection menu to select from a list of items + /// Run a selection menu to select from a list of items static TOOL_ACTION selectionMenu; - /// Selects tracks between junctions or expands an existing selection to pads or the + /// Select tracks between junctions or expands an existing selection to pads or the /// entire connection. static TOOL_ACTION selectConnection; - /// Selects all connections belonging to a single net. + /// Select all connections belonging to a single net. static TOOL_ACTION selectNet; - /// Removes all connections belonging to a single net from the active selection + /// Remove all connections belonging to a single net from the active selection static TOOL_ACTION deselectNet; - /// Selects all components on sheet from Eeschema crossprobing. + /// Select all components on sheet from Eeschema crossprobing. static TOOL_ACTION selectOnSheetFromEeschema; - /// Selects all components on the same sheet as the selected footprint. + /// Select all components on the same sheet as the selected footprint. static TOOL_ACTION selectSameSheet; - /// Filters the items in the current selection (invokes dialog) + /// Filter the items in the current selection (invokes dialog) static TOOL_ACTION filterSelection; /// move or drag an item @@ -110,10 +111,10 @@ public: /// Mirroring of selected items static TOOL_ACTION mirror; - /// Updates selected tracks & vias to the current track & via dimensions + /// Update selected tracks & vias to the current track & via dimensions static TOOL_ACTION changeTrackWidth; - /// Fillets (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius + /// Fillet (i.e. adds an arc tangent to) all selected straight tracks by a user defined radius static TOOL_ACTION filletTracks; /// Activation of the edit tool @@ -469,7 +470,7 @@ public: static TOOL_ACTION convertToArc; static TOOL_ACTION convertToTracks; - ///> @copydoc COMMON_ACTIONS::TranslateLegacyId() + ///< @copydoc COMMON_ACTIONS::TranslateLegacyId() virtual OPT TranslateLegacyId( int aId ) override; }; diff --git a/pcbnew/tools/pcb_control.h b/pcbnew/tools/pcb_control.h index e61ddfbea5..85395a129b 100644 --- a/pcbnew/tools/pcb_control.h +++ b/pcbnew/tools/pcb_control.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014-2016 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -35,10 +37,9 @@ namespace KIGFX { class PCB_BASE_FRAME; class BOARD_ITEM; + /** - * PCB_CONTROL - * - * Handles actions that are shared between different frames in pcbnew. + * Handle actions that are shared between different frames in PcbNew. */ class PCB_CONTROL : public PCB_TOOL_BASE @@ -92,12 +93,13 @@ public: int AppendBoard( PLUGIN& pi, wxString& fileName ); int UpdateMessagePanel( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Sets up handlers for various events. void setTransitions() override; private: /** * Add and select or just select for move/place command a list of board items. + * * @param aItems is the list of items * @param aIsNew = true to add items to the current board, false to just select if * items are already managed by the current board @@ -108,10 +110,10 @@ private: int placeBoardItems( BOARD* aBoard, bool aAnchorAtOrigin ); - ///> Pointer to the currently used edit frame. + ///< Pointer to the currently used edit frame. PCB_BASE_FRAME* m_frame; - ///> Grid origin marker. + ///< Grid origin marker. std::unique_ptr m_gridOrigin; BOARD_ITEM* m_pickerItem; diff --git a/pcbnew/tools/pcb_editor_conditions.h b/pcbnew/tools/pcb_editor_conditions.h index 273193ce1d..e347f830d1 100644 --- a/pcbnew/tools/pcb_editor_conditions.h +++ b/pcbnew/tools/pcb_editor_conditions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 Ian McInerney - * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,7 +35,7 @@ class EDA_DRAW_FRAME; class PCB_BASE_FRAME; /** - * Class that groups generic conditions for PCB editor states. + * Group generic conditions for PCB editor states. */ class PCB_EDITOR_CONDITIONS : public EDITOR_CONDITIONS { @@ -45,56 +45,56 @@ public: {} /** - * Creates a functor that tests if there are items in the board + * Create a functor that tests if there are items in the board * * @return Functor returning true if the the current board has items */ SELECTION_CONDITION HasItems(); /** - * Creates a functor that tests if the pad numbers are displayed + * Create a functor that tests if the pad numbers are displayed * * @return Functor returning true if the pad numbers are displayed */ SELECTION_CONDITION PadNumbersDisplay(); /** - * Creates a functor that tests if the frame fills the pads + * Create a functor that tests if the frame fills the pads * * @return Functor returning true if the pads are filled */ SELECTION_CONDITION PadFillDisplay(); /** - * Creates a functor that tests if the frame fills text items + * Create a functor that tests if the frame fills text items * * @return Functor returning true if the text items are filled */ SELECTION_CONDITION TextFillDisplay(); /** - * Creates a functor that tests if the frame fills graphics items + * Create a functor that tests if the frame fills graphics items * * @return Functor returning true if graphics items are filled */ SELECTION_CONDITION GraphicsFillDisplay(); /** - * Creates a functor that tests if the frame fills vias + * Create a functor that tests if the frame fills vias * * @return Functor returning true if vias are filled */ SELECTION_CONDITION ViaFillDisplay(); /** - * Creates a functor that tests if the frame fills vias + * Create a functor that tests if the frame fills vias * * @return Functor returning true if tracks are filled */ SELECTION_CONDITION TrackFillDisplay(); /** - * Creates a functor that tests the current zone display mode in the frame + * Create a functor that tests the current zone display mode in the frame * * @param aMode is the mode to test for * @return Functor returning true if the frame is using the specified mode @@ -102,28 +102,28 @@ public: SELECTION_CONDITION ZoneDisplayMode( ZONE_DISPLAY_MODE aMode ); protected: - ///> Helper function used by HasItems() + ///< Helper function used by HasItems() static bool hasItemsFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by PadNumbersDisplay() + ///< Helper function used by PadNumbersDisplay() static bool padNumberDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by PadFillDisplay() + ///< Helper function used by PadFillDisplay() static bool padFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by TextFillDisplay() + ///< Helper function used by TextFillDisplay() static bool textFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by GraphicsFillDisplay() + ///< Helper function used by GraphicsFillDisplay() static bool graphicsFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by ViaFillDisplay() + ///< Helper function used by ViaFillDisplay() static bool viaFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by TrackFillDisplay() + ///< Helper function used by TrackFillDisplay() static bool trackFillDisplayFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame ); - ///> Helper function used by ZoneDisplayMode() + ///< Helper function used by ZoneDisplayMode() static bool zoneDisplayModeFunc( const SELECTION& aSelection, PCB_BASE_FRAME* aFrame, ZONE_DISPLAY_MODE aMode ); }; diff --git a/pcbnew/tools/pcb_picker_tool.h b/pcbnew/tools/pcb_picker_tool.h index ed6100b5f1..23abc914b8 100644 --- a/pcbnew/tools/pcb_picker_tool.h +++ b/pcbnew/tools/pcb_picker_tool.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -29,7 +31,7 @@ #include /** - * @brief Generic tool for picking an item. + *Generic tool for picking an item. */ class PCB_PICKER_TOOL : public PCB_TOOL_BASE { @@ -37,7 +39,7 @@ public: PCB_PICKER_TOOL(); ~PCB_PICKER_TOOL() override { } - ///> Event handler types. + ///< Event handler types. typedef std::function CLICK_HANDLER; typedef std::function MOTION_HANDLER; typedef std::function CANCEL_HANDLER; @@ -52,15 +54,14 @@ public: EXCEPTION_CANCEL }; - ///> @copydoc TOOL_INTERACTIVE::Reset() + ///< @copydoc TOOL_INTERACTIVE::Reset() void Reset( RESET_REASON aReason ) override {} - ///> Main event loop. + ///< Main event loop. int Main( const TOOL_EVENT& aEvent ); /** - * Function SetLayerSet() - * Sets the tool's snap layer set + * Set the tool's snap layer set. */ inline void SetLayerSet( LSET aLayerSet ) { m_layerMask = aLayerSet; } @@ -68,8 +69,7 @@ public: inline void SetSnapping( bool aSnap ) { m_snap = aSnap; } /** - * Function SetClickHandler() - * Sets a handler for mouse click event. Handler may decide to receive further click by + * Set a handler for mouse click event. Handler may decide to receive further click by * returning true. */ inline void SetClickHandler( CLICK_HANDLER aHandler ) @@ -79,8 +79,7 @@ public: } /** - * Function SetMotionHandler() - * Sets a handler for mouse motion. Used for roll-over highlighting. + * Set a handler for mouse motion. Used for roll-over highlighting. */ inline void SetMotionHandler( MOTION_HANDLER aHandler ) { @@ -89,8 +88,7 @@ public: } /** - * Function SetCancelHandler() - * Sets a handler for cancel events (ESC or context-menu Cancel). + * Set a handler for cancel events (ESC or context-menu Cancel). */ inline void SetCancelHandler( CANCEL_HANDLER aHandler ) { @@ -99,8 +97,7 @@ public: } /** - * Function SetFinalizeHandler() - * Sets a handler for the finalize event. Takes the state of the exit from the Main loop + * Set a handler for the finalize event. Takes the state of the exit from the Main loop. */ inline void SetFinalizeHandler( FINALIZE_HANDLER aHandler ) { @@ -108,18 +105,17 @@ public: m_finalizeHandler = aHandler; } -private: - ///> @copydoc TOOL_INTERACTIVE::setTransitions(); + ///< @copydoc TOOL_INTERACTIVE::setTransitions(); void setTransitions() override; - ///> Reinitializes tool to its initial state. + ///< Reinitialize tool to its initial state. void reset(); - ///> Applies the requested VIEW_CONTROLS settings. + ///< Apply the requested VIEW_CONTROLS settings. void setControls(); private: - ///> The layer set to use for optional snapping + ///< The layer set to use for optional snapping. LSET m_layerMask; KICURSOR m_cursor; bool m_snap; diff --git a/pcbnew/tools/pcb_point_editor.h b/pcbnew/tools/pcb_point_editor.h index b57d05a75b..5eb18649e1 100644 --- a/pcbnew/tools/pcb_point_editor.h +++ b/pcbnew/tools/pcb_point_editor.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -36,8 +38,6 @@ class PCB_SELECTION_TOOL; class SHAPE_POLY_SET; /** - * PCB_POINT_EDITOR - * * Tool that displays edit points allowing to modify items by dragging the points. */ class PCB_POINT_EDITOR : public PCB_TOOL_BASE @@ -52,46 +52,46 @@ public: bool Init() override; /** - * Function OnSelected() - * * Change selection event handler. */ int OnSelectionChange( const TOOL_EVENT& aEvent ); /** - * Indicates the cursor is over an edit point. Used to coordinate cursor shapes with - * other tools. + * Indicate the cursor is over an edit point. + * + * Used to coordinate cursor shapes with other tools. */ bool HasPoint() { return m_editedPoint != nullptr; } private: - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; void buildForPolyOutline( std::shared_ptr points, const SHAPE_POLY_SET* aOutline ); std::shared_ptr makePoints( EDA_ITEM* aItem ); - ///> Updates item's points with edit points. + ///< Update item's points with edit points. void updateItem() const; - ///> Applies the last changes to the edited item. + ///< Apply the last changes to the edited item. void finishItem(); /** - * Validates a polygon and displays a popup warning if invalid. + * Validate a polygon and displays a popup warning if invalid. + * * @param aModified is the polygon to be checked. * @return True if polygon is valid. */ bool validatePolygon( SHAPE_POLY_SET& aModified ) const; - ///> Updates edit points with item's points. + ///< Update edit points with item's points. void updatePoints(); - ///> Updates which point is being edited. + ///< Update which point is being edited. void updateEditedPoint( const TOOL_EVENT& aEvent ); - ///> Sets the current point being edited. NULL means none. + ///< Set the current point being edited. NULL means none. void setEditedPoint( EDIT_POINT* aPoint ); inline int getEditedPointIndex() const @@ -105,25 +105,25 @@ private: return wxNOT_FOUND; } - ///> Returns true if aPoint is the currently modified point. + ///< Return true if aPoint is the currently modified point. inline bool isModified( const EDIT_POINT& aPoint ) const { return m_editedPoint == &aPoint; } - ///> Sets up an alternative constraint (typically enabled upon a modifier key being pressed). + ///< Set up an alternative constraint (typically enabled upon a modifier key being pressed). void setAltConstraint( bool aEnabled ); - ///> Returns a point that should be used as a constrainer for 45 degrees mode. + ///< Return a point that should be used as a constrainer for 45 degrees mode. EDIT_POINT get45DegConstrainer() const; - ///> Condition to display "Create corner" context menu entry. + ///< Condition to display "Create corner" context menu entry. static bool addCornerCondition( const SELECTION& aSelection ); - ///> Determine if the tool can currently add a corner to the given item + ///< Determine if the tool can currently add a corner to the given item static bool canAddCorner( const EDA_ITEM& aItem ); - ///> Condition to display "Remove corner" context menu entry. + ///< Condition to display "Remove corner" context menu entry. bool removeCornerCondition( const SELECTION& aSelection ); /// TOOL_ACTION handlers @@ -155,10 +155,9 @@ private: void editArcMidKeepCenter( PCB_SHAPE* aArc, VECTOR2I aCenter, VECTOR2I aStart, VECTOR2I aMid, VECTOR2I aEnd, const VECTOR2I aCursor ) const; - ///> Change the edit method to an alternative method ( currently, arcs only ) + ///< Change the edit method to an alternative method ( currently, arcs only ) int changeEditMethod( const TOOL_EVENT& aEvent ); -private: PCB_SELECTION_TOOL* m_selectionTool; std::unique_ptr m_statusPopup; std::shared_ptr m_editPoints; @@ -166,7 +165,7 @@ private: EDIT_POINT* m_editedPoint; EDIT_POINT* m_hoveredPoint; - EDIT_POINT m_original; ///> Original position for the current drag point. + EDIT_POINT m_original; ///< Original position for the current drag point. bool m_refill; bool m_altEditMethod; diff --git a/pcbnew/tools/pcb_selection_conditions.h b/pcbnew/tools/pcb_selection_conditions.h index ca590d381b..dc3963d9e7 100644 --- a/pcbnew/tools/pcb_selection_conditions.h +++ b/pcbnew/tools/pcb_selection_conditions.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -34,35 +36,39 @@ class PCB_SELECTION_CONDITIONS : public SELECTION_CONDITIONS { public: /** - * Function OnlyConnectedItems - * Tests if selection contains exclusively connected items (pads, tracks, vias, zones). + * Test if selection contains exclusively connected items (pads, tracks, vias, zones). + * * @param aSelection is the selection to be tested. * @return True if there are only connected items connected. */ static bool OnlyConnectedItems( const SELECTION& aSelection ); /** - * Function SameNet - * Creates a functor that tests if selection contains items belonging to the same net or are + * Create a functor that tests if selection contains items belonging to the same net or are * unconnected if aAllowUnconnected == true. + * * @param aAllowUnconnected determines if unconnected items (with no net code assigned) should - * be treated as connected to the same net. + * be treated as connected to the same net. * @return Functor testing if selected items are belonging to the same net. */ static SELECTION_CONDITION SameNet( bool aAllowUnconnected = false ); /** - * Function SameLayer * Creates a functor that tests if selection contains items that belong exclusively to the same - * layer. In case of items belonging to multiple layers, it is enough to have a single common - * layer with other items. + * layer. + * + * In case of items belonging to multiple layers, it is enough to have a single common layer + * with other items. + * * @return Functor testing if selected items share at least one common layer. */ static SELECTION_CONDITION SameLayer(); /** - * Creates a functor that tests if the selection contains PCB_SHAPE* items of certain shapes - * This implicitly includes an OnlyType( PCB_SHAPE_T ) as part of the test + * Create a functor that tests if the selection contains PCB_SHAPE* items of certain shapes. + * + * This implicitly includes an OnlyType( PCB_SHAPE_T ) as part of the test. + * * @param aTypes is a list of allowed PCB_SHAPE shapes (@see PCB_SHAPE_TYPE_T) * @return functor testing if selected items match the given list of allowed shapes */ @@ -70,13 +76,13 @@ public: private: - ///> Helper function used by SameNet() + ///< Helper function used by SameNet() static bool sameNetFunc( const SELECTION& aSelection, bool aAllowUnconnected ); - ///> Helper function used by SameLayer() + ///< Helper function used by SameLayer() static bool sameLayerFunc( const SELECTION& aSelection ); - ///> Helper function used by OnlyGraphicShapeTypes() + ///< Helper function used by OnlyGraphicShapeTypes() static bool onlyGraphicShapeTypesFunc( const SELECTION& aSelection, const std::set aTypes ); }; diff --git a/pcbnew/tools/pcb_selection_tool.h b/pcbnew/tools/pcb_selection_tool.h index b196279ebb..a9b7722f7e 100644 --- a/pcbnew/tools/pcb_selection_tool.h +++ b/pcbnew/tools/pcb_selection_tool.h @@ -2,9 +2,10 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN + * Copyright (C) 2017-2021 KiCad Developers, see CHANGELOG.TXT for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski - * Copyright (C) 2017-2020 KiCad Developers, see CHANGELOG.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -51,9 +52,7 @@ typedef void (*CLIENT_SELECTION_FILTER)( const VECTOR2I&, GENERAL_COLLECTOR&, PC /** - * PCB_SELECTION_TOOL - * - * Our sample selection tool: currently supports: + * The selection tool: currently supports: * - pick single objects (click LMB) * - add objects to existing selection (Shift+LMB) * - draw selection box (drag LMB) @@ -74,95 +73,89 @@ public: void Reset( RESET_REASON aReason ) override; /** - * Function Main() - * * The main loop. */ int Main( const TOOL_EVENT& aEvent ); /** - * Function GetSelection() - * - * Returns the set of currently selected items. + * Return the set of currently selected items. */ PCB_SELECTION& GetSelection(); /** - * Function RequestSelection() + * Return the current selection set, filtered according to aFlags and aClientFilter. * - * Returns the current selection set, filtered according to aFlags and aClientFilter. * If the set is empty, performs the legacy-style hover selection. * * @param aConfirmLockedItems if true the user will be prompted if they want to drop locked - * items from the selection or override the locks + * items from the selection or override the locks. */ PCB_SELECTION& RequestSelection( CLIENT_SELECTION_FILTER aClientFilter, bool aConfirmLockedItems = false ); - ///> Select a single item under cursor event handler. + ///< Select a single item under cursor event handler. int CursorSelection( const TOOL_EVENT& aEvent ); - ///> Clear current selection event handler. + ///< Clear current selection event handler. int ClearSelection( const TOOL_EVENT& aEvent ); void ClearSelection( bool aQuietMode = false ); - ///> Item selection event handler. + ///< Item selection event handler. int SelectItem( const TOOL_EVENT& aEvent ); void AddItemToSel( BOARD_ITEM* aItem, bool aQuietMode = false ); - ///> Select all items on the board + ///< Select all items on the board int SelectAll( const TOOL_EVENT& aEvent ); - ///> Multiple item selection event handler + ///< Multiple item selection event handler int SelectItems( const TOOL_EVENT& aEvent ); - ///> Item unselection event handler. + ///< Item unselection event handler. int UnselectItem( const TOOL_EVENT& aEvent ); void RemoveItemFromSel( BOARD_ITEM* aItem, bool aQuietMode = false ); - ///> Multiple item unselection event handler + ///< Multiple item unselection event handler int UnselectItems( const TOOL_EVENT& aEvent ); void BrightenItem( BOARD_ITEM* aItem ); void UnbrightenItem( BOARD_ITEM* aItem ); /** - * Function select() - * Takes necessary action mark an item as selected. + * Take necessary action mark an item as selected. * * @param aItem is an item to be selected. */ void select( BOARD_ITEM* aItem ); /** - * Function selectable() - * Checks conditions for an item to be selected. + * Check conditions for an item to be selected. * * @return True if the item fulfills conditions to be selected. */ bool Selectable( const BOARD_ITEM* aItem, bool checkVisibilityOnly = false ) const; /** - * Function guessSelectionCandidates() - * Tries to guess best selection candidates in case multiple items are clicked, by doing + * Try to guess best selection candidates in case multiple items are clicked, by doing * some brain-dead heuristics. + * * @param aCollector is the collector that has a list of items to be queried. * @param aWhere is the selection point to consider */ void GuessSelectionCandidates( GENERAL_COLLECTOR& aCollector, const VECTOR2I& aWhere ) const; /** - * Function SelectionMenu() - * Shows a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single + * Show a popup menu to trim the COLLECTOR passed as aEvent's parameter down to a single * item. * - * NOTE: this routine DOES NOT modify the selection. + * @note This routine **does not** modify the selection. */ int SelectionMenu( const TOOL_EVENT& aEvent ); /** - * Rebuilds the selection from the EDA_ITEMs' selection flags. Commonly called after - * rolling back an undo state to make sure there aren't any stale pointers. + * Rebuild the selection from the EDA_ITEMs' selection flags. + * + * Commonly called after rolling back an undo state to make sure there aren't any stale + * pointers. */ void RebuildSelection(); @@ -171,10 +164,10 @@ public: return m_filter; } - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; - ///> Zooms the screen to center and fit the current selection. + ///< Zoom the screen to center and fit the current selection. void zoomFitSelection(); BOARD* GetBoard() const @@ -195,20 +188,22 @@ public: PCB_GROUP* GetEnteredGroup() { return m_enteredGroup; } - ///> Applies the SELECTION_FILTER_OPTIONS to a collection of items + ///< Apply the SELECTION_FILTER_OPTIONS to a collection of items void FilterCollectedItems( GENERAL_COLLECTOR& aCollector ); private: /** - * Function selectPoint() - * Selects an item pointed by the parameter aWhere. If there is more than one item at that - * place, there is a menu displayed that allows one to choose the item. + * Select an item pointed by the parameter \a aWhere. + * + * If there is more than one item at that place, there is a menu displayed that allows + * one to choose the item. * * @param aWhere is the place where the item should be selected. * @param aOnDrag indicates whether a drag operation is being performed. * @param aSelectionCancelledFlag allows the function to inform its caller that a selection - * was cancelled (for instance, by clicking outside of the disambiguation menu). + * was canceled (for instance, by clicking outside of the + * disambiguation menu). * @param aClientFilter allows the client to perform tool- or action-specific filtering. * @return True if an item was selected, false otherwise. */ @@ -217,9 +212,9 @@ private: CLIENT_SELECTION_FILTER aClientFilter = NULL ); /** - * Function selectCursor() - * Selects an item under the cursor unless there is something already selected or aSelectAlways - * is true. + * Select an item under the cursor unless there is something already selected or + * \a aSelectAlways is true. + * * @param aForceSelect forces to select an item even if there is an item already selected. * @param aClientFilter allows the client to perform tool- or action-specific filtering. * @return true if eventually there is an item selected, false otherwise. @@ -228,99 +223,98 @@ private: CLIENT_SELECTION_FILTER aClientFilter = NULL ); /** - * Function selectMultiple() - * Handles drawing a selection box that allows one to select many items at - * the same time. + * Handle drawing a selection box that allows one to select many items at the same time. * - * @return true if the function was cancelled (i.e. CancelEvent was received). + * @return true if the function was canceled (i.e. CancelEvent was received). */ bool selectMultiple(); /** - * Allows the selection of a single item from a list via pop-up menu. The items are - * highlighted on the canvas when hovered in the menu. The collector is trimmed to - * the picked item. + * Allow the selection of a single item from a list via pop-up menu. + * + * The items are highlighted on the canvas when hovered in the menu. The collector is + * trimmed to the picked item. + * * @return true if an item was picked */ bool doSelectionMenu( GENERAL_COLLECTOR* aItems ); /** - * Expands the current track selection to the next boundary (junctions, pads, or all) + * Expand the current track selection to the next boundary (junctions, pads, or all) */ int expandConnection( const TOOL_EVENT& aEvent ); /** - * Selects all copper connections belonging to the same net(s) as the - * items in the selection + * Select all copper connections belonging to the same net(s) as the items in the selection */ int selectNet( const TOOL_EVENT& aEvent ); enum STOP_CONDITION { - /** Stop at any place where more than two traces meet + /** + * Stop at any place where more than two traces meet. * - * Because vias are also traces, this makes selection stop at a - * via if there is a trace on another layer as well, but a via - * with only one connection will be selected. */ + * Because vias are also traces, this makes selection stop at a via if there is a trace + * on another layer as well, but a via with only one connection will be selected. + */ STOP_AT_JUNCTION, - /** Stop when reaching a pad */ + /** Stop when reaching a pad. */ STOP_AT_PAD, - /** Select the entire net */ + /** Select the entire net. */ STOP_NEVER }; /** - * Selects connecteed tracks and vias. + * Select connected tracks and vias. * * @param aStopCondition where to stop selecting more items */ void selectConnectedTracks( BOARD_CONNECTED_ITEM& aSourceItem, STOP_CONDITION aStopCondition ); /** - * Selects all items with the given net code + * Select all items with the given net code. + * * @param aNetCode is the target net to select * @param aSelect is true to add the items to the selection, false to remove them (deselect) */ void selectAllItemsOnNet( int aNetCode, bool aSelect = true ); /** - * Selects all items with the given sheet timestamp/UUID name - * (the sheet path) - * The path of the root sheet is "/" + * Select all items with the given sheet timestamp/UUID name (the sheet path). + * + * The path of the root sheet is "/". */ void selectAllItemsOnSheet( wxString& aSheetPath ); - ///> Selects all footprints belonging to same sheet, from Eeschema, - ///> using crossprobing + ///< Select all footprints belonging to same sheet, from Eeschema using cross-probing. int selectSheetContents( const TOOL_EVENT& aEvent ); - ///> Selects all footprints belonging to same hierarchical sheet - ///> as the selected footprint (same sheet path). + ///< Select all footprints belonging to same hierarchical sheet as the selected footprint + ///< (same sheet path). int selectSameSheet( const TOOL_EVENT& aEvent ); - ///> Find dialog callback. + ///< Find dialog callback. void findCallback( BOARD_ITEM* aItem ); - ///> Find an item. + ///< Find an item. int find( const TOOL_EVENT& aEvent ); - ///> Invoke filter dialog and modify current selection + ///< Invoke filter dialog and modify current selection int filterSelection( const TOOL_EVENT& aEvent ); - ///> Returns true if the given item passes the current SELECTION_FILTER_OPTIONS + ///< Return true if the given item passes the current SELECTION_FILTER_OPTIONS. bool itemPassesFilter( BOARD_ITEM* aItem ); /** - * Function unselect() - * Takes necessary action mark an item as unselected. + * Take necessary action mark an item as unselected. * * @param aItem is an item to be unselected. */ void unselect( BOARD_ITEM* aItem ); /** - * Function highlight() - * Highlights the item visually. + * Highlight the item visually. + * * @param aItem is an item to be be highlighted. * @param aHighlightMode should be either SELECTED or BRIGHTENED * @param aGroup is the group to add the item to in the BRIGHTENED mode. @@ -328,8 +322,8 @@ private: void highlight( BOARD_ITEM* aItem, int aHighlightMode, PCB_SELECTION* aGroup = nullptr ); /** - * Function unhighlight() - * Unhighlights the item visually. + * Unhighlight the item visually. + * * @param aItem is an item to be be highlighted. * @param aHighlightMode should be either SELECTED or BRIGHTENED * @param aGroup is the group to remove the item from. @@ -337,7 +331,6 @@ private: void unhighlight( BOARD_ITEM* aItem, int aHighlightMode, PCB_SELECTION* aGroup = nullptr ); /** - * Function selectionContains() * @return True if the given point is contained in any of selected items' bounding box. */ bool selectionContains( const VECTOR2I& aPoint ) const; diff --git a/pcbnew/tools/pcb_viewer_tools.h b/pcbnew/tools/pcb_viewer_tools.h index 1c555b7240..eb6ffdc873 100644 --- a/pcbnew/tools/pcb_viewer_tools.h +++ b/pcbnew/tools/pcb_viewer_tools.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -30,11 +30,10 @@ class PCB_BASE_FRAME; /** - * PCB_VIEWER_TOOLS + * Tool useful for viewing footprints. * - * Tools useful for viewing footprints. - * This tool is designed to be lighter-weight so that it doesn't - * bring in as many pcbnew dependencies (since it is used in cvpcb). + * This tool is designed to be lighter-weight so that it doesn't bring in as many PcbNew + * dependencies (since it is used in cvpcb). */ class PCB_VIEWER_TOOLS : public TOOL_INTERACTIVE { @@ -51,7 +50,7 @@ public: /// @copydoc TOOL_BASE::Reset() void Reset( RESET_REASON aReason ) override; - ///> Launches a tool to measure between points + ///< Launch a tool to measure between points. int MeasureTool( const TOOL_EVENT& aEvent ); // Display modes @@ -64,12 +63,15 @@ public: /// Show the 3D viewer int Show3DViewer( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; /** - * Toggles edit footprint mode. When enabled, one may select parts of footprints individually - * (graphics, pads, etc.), so they can be modified. + * Toggle edit footprint mode. + * + * When enabled, one may select parts of footprints individually (graphics, pads, etc.), + * so they can be modified. + * * @param aEnabled decides if the mode should be enabled. */ void SetFootprintFrame( bool aIsFrame ) @@ -83,8 +85,6 @@ public: } protected: - bool m_footprintFrame; ///< Is this tool associated with a footprint frame - PCB_BASE_FRAME* frame() const { return getEditFrame(); @@ -114,6 +114,8 @@ protected: { return board()->GetFirstFootprint(); } + + bool m_footprintFrame; ///< Is this tool associated with a footprint frame }; #endif diff --git a/pcbnew/tools/placement_tool.h b/pcbnew/tools/placement_tool.h index c8211dc5cd..526722f33a 100644 --- a/pcbnew/tools/placement_tool.h +++ b/pcbnew/tools/placement_tool.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -48,62 +50,58 @@ public: bool Init() override; /** - * Function AlignTop() - * Sets Y coordinate of the selected items to the value of the top-most selected item Y coordinate. + * Set Y coordinate of the selected items to the value of the top-most selected item Y + * coordinate. */ int AlignTop( const TOOL_EVENT& aEvent ); /** - * Function AlignBottom() - * Sets Y coordinate of the selected items to the value of the bottom-most selected item Y coordinate. + * Sets Y coordinate of the selected items to the value of the bottom-most selected item Y + * coordinate. */ int AlignBottom( const TOOL_EVENT& aEvent ); /** - * Function AlignLeft() - * Sets X coordinate of the selected items to the value of the left-most selected item X coordinate. + * Sets X coordinate of the selected items to the value of the left-most selected item X + * coordinate. */ int AlignLeft( const TOOL_EVENT& aEvent ); /** - * Function AlignRight() - * Sets X coordinate of the selected items to the value of the right-most selected item X coordinate. + * Sets X coordinate of the selected items to the value of the right-most selected item X + * coordinate. */ int AlignRight( const TOOL_EVENT& aEvent ); /** - * Function AlignCenterX() - * Sets the x coordinate of the midpoint of each of the selected items to - * the value of the x coordinate of the center of the middle selected item. + * Set the x coordinate of the midpoint of each of the selected items to the value of the + * x coordinate of the center of the middle selected item. */ int AlignCenterX( const TOOL_EVENT& aEvent ); /** - * Function AlignCenterX() - * Sets the y coordinate of the midpoint of each of the selected items to - * the value of the y coordinate of the center of the middle selected item. + * Set the y coordinate of the midpoint of each of the selected items to the value of the + * y coordinate of the center of the middle selected item. */ int AlignCenterY( const TOOL_EVENT& aEvent ); /** - * Function DistributeHorizontally() - * Distributes the selected items along the X axis. + * Distribute the selected items along the X axis. */ int DistributeHorizontally( const TOOL_EVENT& aEvent ); /** - * Function DistributeVertically() - * Distributes the selected items along the Y axis. + * Distribute the selected items along the Y axis. */ int DistributeVertically( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: /** - * Function GetSelections() - * Populates two vectors with the sorted selection and sorted locked items + * Populate two vectors with the sorted selection and sorted locked items. + * * Returns the size of aItemsToAlign() */ template< typename T > @@ -114,56 +112,61 @@ private: int selectTarget( ALIGNMENT_RECTS& aItems, ALIGNMENT_RECTS& aLocked, T aGetValue ); /** - * Sets X coordinate of the selected items to the value of the left-most selected item X coordinate. + * Sets X coordinate of the selected items to the value of the left-most selected item + * X coordinate. * - * NOTE: Uses the bounding box of items, which do not get mirrored even when - * the view is mirrored! + * @note Uses the bounding box of items, which do not get mirrored even when + * the view is mirrored! */ int doAlignLeft(); /** - * Aligns selected items using the right edge of their bounding boxes to the right-most item + * Align selected items using the right edge of their bounding boxes to the right-most item. * - * NOTE: Uses the bounding box of items, which do not get mirrored even when - * the view is mirrored! + * @note Uses the bounding box of items, which do not get mirrored even when + * the view is mirrored! */ int doAlignRight(); /** - * Distributes selected items using an even spacing between the centers of their bounding boxes + * Distribute selected items using an even spacing between the centers of their bounding + * boxes. * - * NOTE: Using the centers of bounding box of items can give unsatisfactory visual results since - * items of differing widths will be placed with different gaps. Is only used if items overlap + * @note Using the centers of bounding box of items can give unsatisfactory visual results + * since items of differing widths will be placed with different gaps. Is only used if + * items overlap. */ - void doDistributeCentersHorizontally( ALIGNMENT_RECTS &itemsToDistribute, + void doDistributeCentersHorizontally( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit ) const; /** - * Distributes selected items using an even spacing between the centers of their bounding boxes + * Distribute selected items using an even spacing between the centers of their bounding + * boxes. * - * NOTE: Using the centers of bounding box of items can give unsatisfactory visual results since - * items of differing widths will be placed with different gaps. Is only used if items overlap + * @note Using the centers of bounding box of items can give unsatisfactory visual results + * since items of differing widths will be placed with different gaps. Is only used + * if items overlap */ - void doDistributeCentersVertically( ALIGNMENT_RECTS &itemsToDistribute, + void doDistributeCentersVertically( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit ) const; /** * Distributes selected items using an even spacing between their bounding boxes * - * NOTE: Using the edges of bounding box of items is only possible if there is enough space - * between them. If this is not the case, use the center spacing method + * @note Using the edges of bounding box of items is only possible if there is enough space + * between them. If this is not the case, use the center spacing method */ - void doDistributeGapsHorizontally( ALIGNMENT_RECTS &itemsToDistribute, BOARD_COMMIT& aCommit, - const BOARD_ITEM *lastItem, int totalGap ) const; + void doDistributeGapsHorizontally( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit, + const BOARD_ITEM* lastItem, int totalGap ) const; /** * Distributes selected items using an even spacing between their bounding boxes * - * NOTE: Using the edges of bounding box of items is only possible if there is enough space - * between them. If this is not the case, use the center spacing method + * @note Using the edges of bounding box of items is only possible if there is enough space + * between them. If this is not the case, use the center spacing method */ - void doDistributeGapsVertically( ALIGNMENT_RECTS &itemsToDistribute, BOARD_COMMIT& aCommit, - const BOARD_ITEM *lastItem, int totalGap ) const; + void doDistributeGapsVertically( ALIGNMENT_RECTS& itemsToDistribute, BOARD_COMMIT& aCommit, + const BOARD_ITEM* lastItem, int totalGap ) const; private: PCB_SELECTION_TOOL* m_selectionTool; diff --git a/pcbnew/tools/position_relative_tool.h b/pcbnew/tools/position_relative_tool.h index 126457cb98..45b8db0edb 100644 --- a/pcbnew/tools/position_relative_tool.h +++ b/pcbnew/tools/position_relative_tool.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -36,10 +36,10 @@ class PCB_SELECTION_TOOL; class DIALOG_POSITION_RELATIVE; /** - * POSITION_RELATIVE_TOOL + * The interactive edit tool. * - * The interactive edit tool. Allows one to move, rotate, flip and change properties of items selected - * using the pcbnew.InteractiveSelection tool. + * Allows one to move, rotate, flip and change properties of items selected using the + * pcbnew.InteractiveSelection tool. */ class POSITION_RELATIVE_TOOL : public PCB_TOOL_BASE @@ -53,37 +53,28 @@ public: bool Init() override; /** - * Function PositionRelative() - * - * Invokes a dialog box to allow positioning of the item relative to another by an exact amount. + * Invoke a dialog box to allow positioning of the item relative to another by an exact amount. */ int PositionRelative( const TOOL_EVENT& aEvent ); /** - * Function SelectPositionRelativeItem() - * - * Invokes the picker tool to select the item to which the previous selection will be placed + * Invoke the picker tool to select the item to which the previous selection will be placed * relative to. */ int SelectPositionRelativeItem( const TOOL_EVENT& aEvent ); /** - * Function GetSelectionAnchorPosition() - * - * Returns the postion of the selected item(s) - * + * Return the position of the selected item(s) */ wxPoint GetSelectionAnchorPosition() const { return m_selectionAnchor; } /** - * Function RelativeItemSelectionMove() - * - * Positions the m_position_relative_selection selection relative to anchorpostion using + * Position the m_position_relative_selection selection relative to anchor position using * the given translation. */ int RelativeItemSelectionMove( wxPoint anchor, wxPoint translation ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; private: diff --git a/pcbnew/tools/zone_create_helper.h b/pcbnew/tools/zone_create_helper.h index 5c66c06006..33f8bf27bd 100644 --- a/pcbnew/tools/zone_create_helper.h +++ b/pcbnew/tools/zone_create_helper.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017-2019 Kicad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2017-2021 Kicad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,38 +35,37 @@ class VIEW; } /** - * This class is an adjuct helper to the DRAWING_TOOL interactive tool, which handles incoming - * geometry changes from a POLYGON_GEOM_MANAGER and translates that into a ZONE based on given - * parameters + * An adjunct helper to the DRAWING_TOOL interactive tool, which handles incoming geometry + * changes from a #POLYGON_GEOM_MANAGER and translates that into a ZONE based on given + * parameters. */ class ZONE_CREATE_HELPER : public POLYGON_GEOM_MANAGER::CLIENT { public: - /** * Parameters used to fully describe a zone creation process */ struct PARAMS { - ///> Should create a keepout zone? + ///< Should create a keepout zone? bool m_keepout; - ///> Layer to begin drawing + ///< Layer to begin drawing PCB_LAYER_ID m_layer; - ///> The zone mode to operate in + ///< The zone mode to operate in ZONE_MODE m_mode; - ///> Zone settings source (for similar and cutout zones) + ///< Zone settings source (for similar and cutout zones) ZONE* m_sourceZone; - ///> Zone leader mode + ///< Zone leader mode POLYGON_GEOM_MANAGER::LEADER_MODE m_leaderMode; }; /** - * @param aTool the DRAWING_TOOL to provide the zone tool to - * @param aParams the parameters to use to guide the zone creation + * @param aTool the #DRAWING_TOOL to provide the zone tool to. + * @param aParams the parameters to use to guide the zone creation. */ ZONE_CREATE_HELPER( DRAWING_TOOL& aTool, PARAMS& aParams ); @@ -75,9 +74,8 @@ public: ZONE* GetZone() const { return m_zone.get(); } /* - * Interface for receiving POLYGON_GEOM_MANAGER update + * Interface for receiving #POLYGON_GEOM_MANAGER update */ - void OnGeometryChange( const POLYGON_GEOM_MANAGER& aMgr ) override; bool OnFirstPoint( POLYGON_GEOM_MANAGER& aMgr ) override; @@ -85,10 +83,7 @@ public: void OnComplete( const POLYGON_GEOM_MANAGER& aMgr ) override; /** - * Function createNewZone() - * - * Prompt the user for new zone settings, and create a new zone with - * those settings + * Prompt the user for new zone settings, and create a new zone with those settings. * * @param aKeepout should the zone be a keepout * @return the new zone, can be null if the user aborted @@ -96,9 +91,7 @@ public: std::unique_ptr createNewZone( bool aKeepout ); /** - * Function createZoneFromExisting - * - * Create a new zone with the settings from an existing zone + * Create a new zone with the settings from an existing zone. * * @param aSrcZone the zone to copy settings from * @return the new zone @@ -106,10 +99,7 @@ public: std::unique_ptr createZoneFromExisting( const ZONE& aSrcZone ); /** - * Function performZoneCutout() - * - * Cut one zone out of another one (i.e. subtraction) and - * update the zone. + * Cut one zone out of another one (i.e. subtraction) and update the zone.. * * @param aZone the zone to removed area from * @param aCutout the area to remove @@ -117,28 +107,28 @@ public: void performZoneCutout( ZONE& aZone, ZONE& aCutout ); /** - * Commit the current zone-in-progress to the BOARD. This might - * be adding a new zone, or modifying an existing zone with a - * cutout, depending on parameters. + * Commit the current zone-in-progress to the BOARD. * - * @param aZone - the drawn zone outline to commit + * This might be adding a new zone, or modifying an existing zone with a cutout, depending + * on parameters. + * + * @param aZone is the drawn zone outline to commit. */ void commitZone( std::unique_ptr aZone ); private: - DRAWING_TOOL& m_tool; - ///> Parameters of the zone to be drawn + ///< Parameters of the zone to be drawn PARAMS& m_params; - ///> The preview item to display + ///< The preview item to display KIGFX::PREVIEW::POLYGON_ITEM m_previewItem; - ///> view that show the preview item + ///< view that show the preview item KIGFX::VIEW& m_parentView; - ///> The zone-in-progress + ///< The zone-in-progress std::unique_ptr m_zone; }; diff --git a/pcbnew/tools/zone_filler_tool.h b/pcbnew/tools/zone_filler_tool.h index 6ed36085dc..fc9db0d6ef 100644 --- a/pcbnew/tools/zone_filler_tool.h +++ b/pcbnew/tools/zone_filler_tool.h @@ -1,7 +1,9 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2014 - 2017 CERN + * Copyright (C) 2014 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -33,9 +35,7 @@ class WX_PROGRESS_REPORTER; /** - * ZONE_FILLER_TOOL - * - * Handles actions specific to filling copper zones. + * Handle actions specific to filling copper zones. */ class ZONE_FILLER_TOOL : public PCB_TOOL_BASE { @@ -55,10 +55,10 @@ public: int ZoneUnfillAll( const TOOL_EVENT& aEvent ); private: - ///> Refocuses on an idle event (used after the Progress Reporter messes up the focus) + ///< Refocus on an idle event (used after the Progress Reporter messes up the focus). void singleShotRefocus( wxIdleEvent& ); - ///> Sets up handlers for various events. + ///< Set up handlers for various events. void setTransitions() override; }; diff --git a/pcbnew/widgets/appearance_controls.h b/pcbnew/widgets/appearance_controls.h index 2564fddfe1..0c4ee23002 100644 --- a/pcbnew/widgets/appearance_controls.h +++ b/pcbnew/widgets/appearance_controls.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2020 Jon Evans - * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2020-2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -201,7 +201,7 @@ public: wxSize GetBestSize() const; - ///> Updates the panel contents from the application and board models + ///< Update the panel contents from the application and board models. void OnBoardChanged(); void OnBoardNetSettingsChanged( BOARD& aBoard ) override; @@ -218,26 +218,26 @@ public: void OnBoardItemsChanged( BOARD& aBoard, std::vector& aBoardItems ) override; - ///> Updates the colors on all the widgets from the new chosen color theme + ///< Update the colors on all the widgets from the new chosen color theme. void OnColorThemeChanged(); - ///> Updates the widget when the active board layer is changed + ///< Update the widget when the active board layer is changed. void OnLayerChanged(); - ///> Manually update visibility for a given layer + ///< Manually update visibility for a given layer void SetLayerVisible( LAYER_NUM aLayer, bool isVisible ); void SetObjectVisible( GAL_LAYER_ID aLayer, bool isVisible = true ); - ///> Updates the manual layer alpha overrides + ///< Update the manual layer alpha overrides. void OnLayerAlphaChanged(); void UpdateDisplayOptions(); - ///> Returns a list of the layer presets created by the user + ///< Return a list of the layer presets created by the user. std::vector GetUserLayerPresets() const; - ///> Updates the current layer presets from those saved in the project file + ///< Update the current layer presets from those saved in the project file. void SetUserLayerPresets( std::vector& aPresetList ); void ApplyLayerPreset( const wxString& aPresetName ); @@ -261,14 +261,13 @@ public: void OnLayerContextMenu( wxCommandEvent& aEvent ); - ///> Returns the index of the current tab (0-2) + ///< Return the index of the current tab (0-2). int GetTabIndex() const; - ///> Sets the current notebook tab + ///< Set the current notebook tab. void SetTabIndex( int aTab ); protected: - void OnNotebookPageChanged( wxNotebookEvent& event ) override; void OnSetFocus( wxFocusEvent& aEvent ) override; @@ -284,122 +283,6 @@ protected: void OnNetGridMouseEvent( wxMouseEvent& aEvent ); private: - PCB_BASE_FRAME* m_frame; - - wxWindow* m_focusOwner; - - static const APPEARANCE_SETTING s_objectSettings[]; - - ROW_ICON_PROVIDER* m_iconProvider; - - BOARD* m_board; - - bool m_isFpEditor; - - // Nets grid view - NET_GRID_TABLE* m_netsTable; - - GRID_BITMAP_TOGGLE_RENDERER* m_toggleGridRenderer; - - /// Grid cell that is being hovered over, for tooltips - wxGridCellCoords m_hoveredCell; - - std::vector> m_layerSettings; - - std::map m_layerSettingsMap; - - std::vector> m_objectSettings; - - std::map m_objectSettingsMap; - - std::vector> m_netclassSettings; - - std::map m_netclassSettingsMap; - - // TODO(JE) Move preset storage to the PCB_CONTROL tool - - // Storage for all layer presets - std::map m_layerPresets; - - LAYER_PRESET* m_currentPreset; - - /// The last user (non-read-only) preset selected by the user - LAYER_PRESET* m_lastSelectedUserPreset; - - wxArrayString m_presetMRU; - - wxMenu* m_layerContextMenu; - - /// Stores wxIDs for each netclass for control event mapping - std::map m_netclassIdMap; - - /// The name of the netclass that was right-clicked - wxString m_contextMenuNetclass; - - wxBoxSizer* m_layersOuterSizer; - wxBoxSizer* m_objectsOuterSizer; - - // The built-in layer presets - - static LAYER_PRESET presetNoLayers; - static LAYER_PRESET presetAllLayers; - static LAYER_PRESET presetAllCopper; - static LAYER_PRESET presetInnerCopper; - static LAYER_PRESET presetFront; - static LAYER_PRESET presetFrontAssembly; - static LAYER_PRESET presetBack; - static LAYER_PRESET presetBackAssembly; - - int m_pointSize; - - wxColour m_layerPanelColour; - - // Layer display options controls - - WX_COLLAPSIBLE_PANE* m_paneLayerDisplayOptions; - wxStaticText* m_staticTextContrastModeTitle; - wxRadioButton* m_rbHighContrastNormal; - wxRadioButton* m_rbHighContrastDim; - wxRadioButton* m_rbHighContrastOff; - wxStaticLine* m_layerDisplaySeparator; - wxCheckBox* m_cbFlipBoard; - - // Net display options controls - - WX_COLLAPSIBLE_PANE* m_paneNetDisplayOptions; - wxStaticText* m_txtNetDisplayTitle; - wxRadioButton* m_rbNetColorAll; - wxRadioButton* m_rbNetColorRatsnest; - wxRadioButton* m_rbNetColorOff; - wxStaticText* m_txtRatsnestVisibility; - wxRadioButton* m_rbRatsnestAllLayers; - wxRadioButton* m_rbRatsnestVisibleLayers; - - enum POPUP_ID - { - ID_CHANGE_COLOR = wxID_HIGHEST, - ID_SET_NET_COLOR, - ID_CLEAR_NET_COLOR, - ID_SHOW_ALL_NETS, - ID_HIDE_OTHER_NETS, - ID_HIGHLIGHT_NET, - ID_SELECT_NET, - ID_DESELECT_NET, - ID_SHOW_ALL_COPPER_LAYERS, - ID_HIDE_ALL_COPPER_LAYERS, - ID_HIDE_ALL_BUT_ACTIVE, - ID_PRESET_NO_LAYERS, - ID_PRESET_ALL_LAYERS, - ID_PRESET_FRONT, - ID_PRESET_FRONT_ASSEMBLY, - ID_PRESET_INNER_COPPER, - ID_PRESET_BACK, - ID_PRESET_BACK_ASSEMBLY, - ID_HIDE_ALL_NON_COPPER, - ID_SHOW_ALL_NON_COPPER, - ID_LAST_VALUE - }; - void createControls(); void rebuildLayers(); @@ -469,6 +352,119 @@ private: bool doesBoardItemNeedRebuild( BOARD_ITEM* aBoardItem ); bool doesBoardItemNeedRebuild( std::vector& aBoardItems ); + + PCB_BASE_FRAME* m_frame; + + wxWindow* m_focusOwner; + + static const APPEARANCE_SETTING s_objectSettings[]; + + ROW_ICON_PROVIDER* m_iconProvider; + + BOARD* m_board; + + bool m_isFpEditor; + + // Nets grid view + NET_GRID_TABLE* m_netsTable; + + GRID_BITMAP_TOGGLE_RENDERER* m_toggleGridRenderer; + + /// Grid cell that is being hovered over, for tooltips + wxGridCellCoords m_hoveredCell; + + std::vector> m_layerSettings; + + std::map m_layerSettingsMap; + + std::vector> m_objectSettings; + + std::map m_objectSettingsMap; + + std::vector> m_netclassSettings; + + std::map m_netclassSettingsMap; + + // TODO(JE) Move preset storage to the PCB_CONTROL tool + + // Storage for all layer presets + std::map m_layerPresets; + + LAYER_PRESET* m_currentPreset; + + /// The last user (non-read-only) preset selected by the user + LAYER_PRESET* m_lastSelectedUserPreset; + + wxArrayString m_presetMRU; + + wxMenu* m_layerContextMenu; + + /// Stores wxIDs for each netclass for control event mapping + std::map m_netclassIdMap; + + /// The name of the netclass that was right-clicked + wxString m_contextMenuNetclass; + + wxBoxSizer* m_layersOuterSizer; + wxBoxSizer* m_objectsOuterSizer; + + // The built-in layer presets + static LAYER_PRESET presetNoLayers; + static LAYER_PRESET presetAllLayers; + static LAYER_PRESET presetAllCopper; + static LAYER_PRESET presetInnerCopper; + static LAYER_PRESET presetFront; + static LAYER_PRESET presetFrontAssembly; + static LAYER_PRESET presetBack; + static LAYER_PRESET presetBackAssembly; + + int m_pointSize; + + wxColour m_layerPanelColour; + + // Layer display options controls + WX_COLLAPSIBLE_PANE* m_paneLayerDisplayOptions; + wxStaticText* m_staticTextContrastModeTitle; + wxRadioButton* m_rbHighContrastNormal; + wxRadioButton* m_rbHighContrastDim; + wxRadioButton* m_rbHighContrastOff; + wxStaticLine* m_layerDisplaySeparator; + wxCheckBox* m_cbFlipBoard; + + // Net display options controls + WX_COLLAPSIBLE_PANE* m_paneNetDisplayOptions; + wxStaticText* m_txtNetDisplayTitle; + wxRadioButton* m_rbNetColorAll; + wxRadioButton* m_rbNetColorRatsnest; + wxRadioButton* m_rbNetColorOff; + wxStaticText* m_txtRatsnestVisibility; + wxRadioButton* m_rbRatsnestAllLayers; + wxRadioButton* m_rbRatsnestVisibleLayers; + + enum POPUP_ID + { + ID_CHANGE_COLOR = wxID_HIGHEST, + ID_SET_NET_COLOR, + ID_CLEAR_NET_COLOR, + ID_SHOW_ALL_NETS, + ID_HIDE_OTHER_NETS, + ID_HIGHLIGHT_NET, + ID_SELECT_NET, + ID_DESELECT_NET, + ID_SHOW_ALL_COPPER_LAYERS, + ID_HIDE_ALL_COPPER_LAYERS, + ID_HIDE_ALL_BUT_ACTIVE, + ID_PRESET_NO_LAYERS, + ID_PRESET_ALL_LAYERS, + ID_PRESET_FRONT, + ID_PRESET_FRONT_ASSEMBLY, + ID_PRESET_INNER_COPPER, + ID_PRESET_BACK, + ID_PRESET_BACK_ASSEMBLY, + ID_HIDE_ALL_NON_COPPER, + ID_SHOW_ALL_NON_COPPER, + ID_LAST_VALUE + }; }; #endif diff --git a/utils/kicad2step/panel_kicad2step.h b/utils/kicad2step/panel_kicad2step.h index fa01ae8fc2..b46ea44f73 100644 --- a/utils/kicad2step/panel_kicad2step.h +++ b/utils/kicad2step/panel_kicad2step.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -23,7 +24,7 @@ /** * @file panel_kicad2step.h - * declares the main PCB object + * Declare the main PCB object. */ #ifndef PANEL_KICAD2STEP_H @@ -38,10 +39,9 @@ class KICAD2MCAD_PRMS // A small class to handle parameters of conversion public: KICAD2MCAD_PRMS(); - ///> Returns file extension for the selected output format + ///< Return file extension for the selected output format wxString getOutputExt() const; -public: #ifdef SUPPORTS_IGES bool m_fmtIGES; #endif @@ -61,14 +61,17 @@ class PANEL_KICAD2STEP: public wxPanel { public: PANEL_KICAD2STEP( wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize( 500,300 ), + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxSize( 500,300 ), long style = wxTAB_TRAVERSAL ); - /** Run the Kicad to STEP converter + /** + * Run the KiCad to STEP converter. */ int RunConverter(); - /** Add a message to m_tcMessages + /** + * Add a message to m_tcMessages. */ void AppendMessage( const wxString& aMessage ); @@ -78,4 +81,4 @@ private: wxTextCtrl* m_tcMessages; }; -#endif // #ifndef PANEL_KICAD2STEP_H \ No newline at end of file +#endif // #ifndef PANEL_KICAD2STEP_H diff --git a/utils/kicad2step/pcb/base.h b/utils/kicad2step/pcb/base.h index 32c617cf15..3b4ae397de 100644 --- a/utils/kicad2step/pcb/base.h +++ b/utils/kicad2step/pcb/base.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 Cirilo Bernardo + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -23,8 +24,7 @@ /** * @file base.h - * provides declarations of items which are basic to all - * kicad2mcad code. + * Provide declarations of items which are basic to all kicad2mcad code. */ #ifndef KICADBASE_H @@ -34,7 +34,7 @@ #include -///> Default minimum distance between points to treat them as separate ones (mm) +///< Default minimum distance between points to treat them as separate ones (mm) static constexpr double MIN_DISTANCE = 0.01; namespace SEXPR @@ -53,9 +53,9 @@ enum CURVE_TYPE /* * Layers of importance to MCAD export: - * LAYER_TOP: specifies that a footprint is on the top of the PCB - * LAYER_BOTTOM: specifies that a footprint is on the bottom of the PCB - * LAYER_EDGE: specifies that a Curve is associated with the PCB edge + * - LAYER_TOP: specifies that a footprint is on the top of the PCB + * - LAYER_BOTTOM: specifies that a footprint is on the bottom of the PCB + * - LAYER_EDGE: specifies that a Curve is associated with the PCB edge */ enum LAYERS { @@ -99,13 +99,12 @@ bool Get3DCoordinate( const SEXPR::SEXPR* data, TRIPLET& aCoordinate ); bool GetXYZRotation( const SEXPR::SEXPR* data, TRIPLET& aRotation ); /** - * Get the layer name from a layer element, if the layer is syntactically - * valid. + * Get the layer name from a layer element, if the layer is syntactically valid. * * E.g. (layer "Edge.Cuts") -> "Edge.Cuts" * - * @param aLayerElem the s-expr element to get the name from - * @return the layer name if valid, else empty + * @param aLayerElem the s-expr element to get the name from. + * @return the layer name if valid, else empty. */ OPT GetLayerName( const SEXPR::SEXPR& aLayerElem ); diff --git a/utils/kicad2step/pcb/kicadcurve.h b/utils/kicad2step/pcb/kicadcurve.h index 809b464f0a..015d10b559 100644 --- a/utils/kicad2step/pcb/kicadcurve.h +++ b/utils/kicad2step/pcb/kicadcurve.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 Cirilo Bernardo + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -23,7 +24,7 @@ /** * @file kicadcurve.h - * declares the Curve (glyph) object. + * Declare the Curve (glyph) object. */ #ifndef KICADCURVE_H @@ -47,7 +48,7 @@ public: return m_layer; } - ///> Returns human-readable description of the curve. + ///< Return human-readable description of the curve. std::string Describe() const; CURVE_TYPE m_form; // form of curve: line, arc, circle