From 7030c9fc4fdac02f29ff4c316fcae1de46d7a37e Mon Sep 17 00:00:00 2001 From: James Crook Date: Sat, 3 Nov 2018 13:17:54 +0000 Subject: [PATCH] More doxygen --- src/FFmpeg.h | 3 ++ src/Menus.cpp | 1 + src/Menus.h | 10 +++++++ src/Prefs.h | 17 ++++++----- src/Track.h | 23 ++++++++------- src/TrackPanelCell.h | 10 ++++--- src/effects/Biquad.h | 2 ++ src/menus/ClipMenus.cpp | 1 + src/menus/ExtraMenus.cpp | 1 + src/menus/LabelMenus.cpp | 1 + src/menus/NavigationMenus.cpp | 1 + src/menus/ToolbarMenus.cpp | 1 + src/menus/WindowMenus.cpp | 1 + src/prefs/BatchPrefs.cpp | 4 +-- src/prefs/BatchPrefs.h | 2 ++ src/prefs/DevicePrefs.h | 1 + src/prefs/DirectoriesPrefs.h | 1 + src/prefs/EffectsPrefs.h | 1 + src/prefs/ExtImportPrefs.h | 1 + src/prefs/GUIPrefs.h | 1 + src/prefs/ImportExportPrefs.h | 1 + src/prefs/KeyConfigPrefs.h | 1 + src/prefs/LibraryPrefs.h | 1 + src/prefs/MidiIOPrefs.h | 1 + src/prefs/ModulePrefs.h | 1 + src/prefs/MousePrefs.h | 1 + src/prefs/PlaybackPrefs.h | 2 ++ src/prefs/PrefsPanel.h | 15 ++++++---- src/prefs/ProjectsPrefs.h | 1 + src/prefs/QualityPrefs.h | 1 + src/prefs/RecordingPrefs.h | 1 + src/prefs/SpectrumPrefs.h | 1 + src/prefs/ThemePrefs.h | 1 + src/prefs/TracksBehaviorsPrefs.h | 1 + src/prefs/TracksPrefs.h | 1 + src/prefs/WarningsPrefs.h | 1 + src/prefs/WaveformPrefs.h | 1 + src/tracks/ui/BackgroundCell.h | 3 ++ src/tracks/ui/ButtonHandle.h | 3 ++ src/widgets/BackedPanel.h | 4 +++ src/widgets/Grabber.h | 6 ++++ src/widgets/Grid.h | 50 +++++++++++++++----------------- src/widgets/LinkingHtmlWindow.h | 6 ++++ 43 files changed, 131 insertions(+), 56 deletions(-) diff --git a/src/FFmpeg.h b/src/FFmpeg.h index 81b714a58..54a2c9d34 100644 --- a/src/FFmpeg.h +++ b/src/FFmpeg.h @@ -952,6 +952,9 @@ private: // utilites for RAII: // Deleter adaptor for functions like av_free that take a pointer + +/// \brief AV_Deleter is part of FFmpeg support. It's used with the RAII +/// idiom. template struct AV_Deleter { inline R operator() (T* p) const { diff --git a/src/Menus.cpp b/src/Menus.cpp index 648db5fec..dad45400f 100644 --- a/src/Menus.cpp +++ b/src/Menus.cpp @@ -81,6 +81,7 @@ void MenuManager::UpdatePrefs() mStopIfWasPaused = true; // not configurable for now, but could be later. } +/// Namespace for structures that go into building a menu namespace MenuTable { BaseItem::~BaseItem() {} diff --git a/src/Menus.h b/src/Menus.h index bb6a64943..2e644bdbb 100644 --- a/src/Menus.h +++ b/src/Menus.h @@ -96,11 +96,14 @@ MenuManager &GetMenuManager(AudacityProject &project); // Exported helper functions from various menu handling source files + +/// Namespace for functions for File menu namespace FileActions { AudacityProject *DoImportMIDI( AudacityProject *pProject, const wxString &fileName ); } +/// Namespace for functions for Edit menu namespace EditActions { bool DoEditMetadata( AudacityProject &project, @@ -109,6 +112,7 @@ void DoReloadPreferences( AudacityProject & ); void DoUndo( AudacityProject &project ); } +/// Namespace for functions for Select menu namespace SelectActions { void DoListSelection( AudacityProject &project, Track *t, @@ -117,12 +121,14 @@ void DoSelectAll( AudacityProject &project ); void DoSelectSomething( AudacityProject &project ); } +/// Namespace for functions for View menu namespace ViewActions { double GetZoomOfToFit( const AudacityProject &project ); void DoZoomFit( AudacityProject &project ); void DoZoomFitV( AudacityProject &project ); } +/// Namespace for functions for Transport menu namespace TransportActions { bool DoPlayStopSelect( AudacityProject &project, bool click, bool shift ); void DoPlayStopSelect( AudacityProject &project ); @@ -134,6 +140,7 @@ void DoTogglePinnedHead( AudacityProject & ); void DoRecord( AudacityProject & ); } +/// Namespace for functions for Track menu namespace TrackActions { enum MoveChoice { OnMoveUpID, OnMoveDownID, OnMoveTopID, OnMoveBottomID @@ -149,6 +156,8 @@ void DoRemoveTrack( AudacityProject &project, Track * toRemove ); void DoRemoveTracks( AudacityProject & ); } + +/// Namespace for helper functions to do with plug ins namespace PluginActions { enum : unsigned { // No flags specified @@ -166,6 +175,7 @@ bool DoAudacityCommand( const PluginID & ID, const CommandContext & context, unsigned flags ); } +/// Namespace for functions for Help menu namespace HelpActions { void DoHelpWelcome( AudacityProject & ); void DoShowLog( AudacityProject& ); diff --git a/src/Prefs.h b/src/Prefs.h index e0a29ed87..961e2fc62 100644 --- a/src/Prefs.h +++ b/src/Prefs.h @@ -45,6 +45,10 @@ class AudacityPrefs; extern AUDACITY_DLL_API AudacityPrefs *gPrefs; extern int gMenusDirty; + +/// \brief Our own specialisation of wxFileConfig. It is essentially a renaming, +/// though it does provide one new access function. Most of the prefs work +/// is actually done by the InitPreferences() function. class AUDACITY_DLL_API AudacityPrefs : public wxFileConfig { public: @@ -57,9 +61,8 @@ public: bool GetEditClipsCanMove(); }; -// Packages a table of user-visible choices each with an internal code string, -// a preference key path, -// and a default choice +/// Packages a table of user-visible choices each with an internal code string, +/// a preference key path, and a default choice class EnumSetting { public: @@ -102,10 +105,10 @@ protected: const size_t mDefaultSymbol; }; -// Extends EnumSetting with a corresponding table of integer codes -// (generally not equal to their table positions), -// and optionally an old preference key path that stored integer codes, to be -// migrated into one that stores internal string values instead +/// Extends EnumSetting with a corresponding table of integer codes +/// (generally not equal to their table positions), +/// and optionally an old preference key path that stored integer codes, to be +/// migrated into one that stores internal string values instead class EncodedEnumSetting : public EnumSetting { public: diff --git a/src/Track.h b/src/Track.h index 84a17cc9b..1aea2ab7a 100644 --- a/src/Track.h +++ b/src/Track.h @@ -86,9 +86,9 @@ enum class TrackKind All }; -// Compile-time function on enum values. -// It knows all inheritance relations among Track subclasses -// even where the track types are only forward declared. +/// Compile-time function on enum values. +/// It knows all inheritance relations among Track subclasses +/// even where the track types are only forward declared. constexpr bool CompatibleTrackKinds( TrackKind desired, TrackKind actual ) { return @@ -110,8 +110,8 @@ constexpr bool CompatibleTrackKinds( TrackKind desired, TrackKind actual ) ; } -// This bit of metaprogramming lets track_cast work even when the track -// subclasses are visible only as incomplete types +/// \brief Metaprogramming in TrackTyper lets track_cast work even when the track +/// subclasses are visible only as incomplete types namespace TrackTyper { template struct Pair; using List = std::tuple< @@ -160,12 +160,13 @@ template class ViewInfo; -// This is an in-session identifier of track objects across undo states -// It does not persist between sessions -// Default constructed value is not equal to the id of any track that has ever -// been added to a TrackList, or (directly or transitively) copied from such -// (A pending additional track that is not yet applied is not considered added) -// TrackIds are assigned uniquely across projects +/// This is an in-session identifier of track objects across undo states +/// +/// It does not persist between sessions +/// Default constructed value is not equal to the id of any track that has ever +/// been added to a TrackList, or (directly or transitively) copied from such +/// (A pending additional track that is not yet applied is not considered added) +/// TrackIds are assigned uniquely across projects class TrackId { public: diff --git a/src/TrackPanelCell.h b/src/TrackPanelCell.h index fcca9fa18..d58898ea6 100644 --- a/src/TrackPanelCell.h +++ b/src/TrackPanelCell.h @@ -28,7 +28,9 @@ using UIHandlePtr = std::shared_ptr; #include -// A subtree in the subdivision of the CellularPanel's area +/// The TrackPanel is built up of nodes, subtrees of the CellularPanel's area +/// This class itself has almost nothing in it. Other classes derived from it +/// build up the capabilities. class AUDACITY_DLL_API /* not final */ TrackPanelNode { public: @@ -36,7 +38,7 @@ public: virtual ~TrackPanelNode() = 0; }; -// A non-leaf +// A node of the TrackPanel that contins other nodes. class AUDACITY_DLL_API TrackPanelGroup /* not final */ : public TrackPanelNode { public: @@ -62,8 +64,8 @@ public: virtual Subdivision Children( const wxRect &rect ) = 0; }; -// Abstract base class defining TrackPanel's access to specialist classes that -// implement drawing and user interactions +/// Abstract base class defining TrackPanel's access to specialist classes that +/// implement drawing and user interactions class AUDACITY_DLL_API TrackPanelCell /* not final */ : public TrackPanelNode { public: diff --git a/src/effects/Biquad.h b/src/effects/Biquad.h index f25d8b9da..5ddd0dd79 100644 --- a/src/effects/Biquad.h +++ b/src/effects/Biquad.h @@ -12,6 +12,8 @@ Max Maisel #ifndef __BIQUAD_H__ #define __BIQUAD_H__ + +/// \brief Represents a biquad digital filter. struct Biquad { Biquad(); diff --git a/src/menus/ClipMenus.cpp b/src/menus/ClipMenus.cpp index dcce5cdbf..c76cf213a 100644 --- a/src/menus/ClipMenus.cpp +++ b/src/menus/ClipMenus.cpp @@ -726,6 +726,7 @@ void DoClipLeftOrRight } +/// Namespace for functions for Clip menu namespace ClipActions { // exported helper functions diff --git a/src/menus/ExtraMenus.cpp b/src/menus/ExtraMenus.cpp index 32d36d3ae..8a48c7669 100644 --- a/src/menus/ExtraMenus.cpp +++ b/src/menus/ExtraMenus.cpp @@ -9,6 +9,7 @@ namespace { } +/// Namespace for helper functions for Extra menu namespace ExtraActions { // exported helper functions diff --git a/src/menus/LabelMenus.cpp b/src/menus/LabelMenus.cpp index ee67b10f1..4d69308fc 100644 --- a/src/menus/LabelMenus.cpp +++ b/src/menus/LabelMenus.cpp @@ -242,6 +242,7 @@ void EditClipboardByLabel( } +/// Namespace for functions for Edit Label submenu namespace LabelEditActions { // exported helper functions diff --git a/src/menus/NavigationMenus.cpp b/src/menus/NavigationMenus.cpp index 610625dc3..c3b88e7b1 100644 --- a/src/menus/NavigationMenus.cpp +++ b/src/menus/NavigationMenus.cpp @@ -290,6 +290,7 @@ void DoNextTrack( } +/// Namespace for functions for project navigation menu (part of Extra menu) namespace NavigationActions { // exported helper functions diff --git a/src/menus/ToolbarMenus.cpp b/src/menus/ToolbarMenus.cpp index 07db21a7d..984a89e5a 100644 --- a/src/menus/ToolbarMenus.cpp +++ b/src/menus/ToolbarMenus.cpp @@ -22,6 +22,7 @@ void SetTool(AudacityProject &project, int tool) } +/// Namespace for functions for View Toolbar menu namespace ToolbarActions { // exported helper functions diff --git a/src/menus/WindowMenus.cpp b/src/menus/WindowMenus.cpp index 3bbfcf22b..bf16e7135 100644 --- a/src/menus/WindowMenus.cpp +++ b/src/menus/WindowMenus.cpp @@ -48,6 +48,7 @@ void DoMacMinimize(AudacityProject *project) } +/// Namespace for functions for window management (mac only?) namespace WindowActions { // exported helper functions diff --git a/src/prefs/BatchPrefs.cpp b/src/prefs/BatchPrefs.cpp index 7bf70ddad..8deb6c05f 100644 --- a/src/prefs/BatchPrefs.cpp +++ b/src/prefs/BatchPrefs.cpp @@ -10,8 +10,8 @@ *******************************************************************//** \class BatchPrefs -\brief A PrefsPanel that builds up a chain of effects in MacroCommands - +\brief A probably unused PrefsPanel that in debug builds could offer a +setting used in debugging batch (aka macros) processing. *//*******************************************************************/ #include "../Audacity.h" diff --git a/src/prefs/BatchPrefs.h b/src/prefs/BatchPrefs.h index e13f8f544..5ab8606b3 100644 --- a/src/prefs/BatchPrefs.h +++ b/src/prefs/BatchPrefs.h @@ -34,6 +34,8 @@ private: DECLARE_EVENT_TABLE() }; + +/// A PrefsPanelFactory that creates one BatchPrefs panel. class BatchPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/DevicePrefs.h b/src/prefs/DevicePrefs.h index 4cfd36f7b..5d92b2390 100644 --- a/src/prefs/DevicePrefs.h +++ b/src/prefs/DevicePrefs.h @@ -54,6 +54,7 @@ class DevicePrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one DevicePrefs panel. class DevicePrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/DirectoriesPrefs.h b/src/prefs/DirectoriesPrefs.h index 3f9ab4a60..96b383dd8 100644 --- a/src/prefs/DirectoriesPrefs.h +++ b/src/prefs/DirectoriesPrefs.h @@ -39,6 +39,7 @@ class DirectoriesPrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one DirectoriesPrefs panel. class DirectoriesPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/EffectsPrefs.h b/src/prefs/EffectsPrefs.h index cd26ba97c..62a14156c 100644 --- a/src/prefs/EffectsPrefs.h +++ b/src/prefs/EffectsPrefs.h @@ -35,6 +35,7 @@ class EffectsPrefs final : public PrefsPanel void Populate(); }; +/// A PrefsPanelFactory that creates one EffectsPrefs panel. class EffectsPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/ExtImportPrefs.h b/src/prefs/ExtImportPrefs.h index e0cdf2073..497c4501e 100644 --- a/src/prefs/ExtImportPrefs.h +++ b/src/prefs/ExtImportPrefs.h @@ -108,6 +108,7 @@ class ExtImportPrefs final : public PrefsPanel }; +/// A PrefsPanelFactory that creates one ExtImportPrefs panel. class ExtImportPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/GUIPrefs.h b/src/prefs/GUIPrefs.h index 9932a2a7c..46e631f2b 100644 --- a/src/prefs/GUIPrefs.h +++ b/src/prefs/GUIPrefs.h @@ -49,6 +49,7 @@ class GUIPrefs final : public PrefsPanel wxArrayString mRangeChoices; }; +/// A PrefsPanelFactory that creates one GUIPrefs panel. class GUIPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/ImportExportPrefs.h b/src/prefs/ImportExportPrefs.h index 0270a6c33..f50cdc03c 100644 --- a/src/prefs/ImportExportPrefs.h +++ b/src/prefs/ImportExportPrefs.h @@ -34,6 +34,7 @@ class ImportExportPrefs final : public PrefsPanel void Populate(); }; +/// A PrefsPanelFactory that creates one ImportExportPrefs panel. class ImportExportPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/KeyConfigPrefs.h b/src/prefs/KeyConfigPrefs.h index e09fa9a3e..3eaa00374 100644 --- a/src/prefs/KeyConfigPrefs.h +++ b/src/prefs/KeyConfigPrefs.h @@ -94,6 +94,7 @@ private: }; +/// A PrefsPanelFactory that creates one KeyConfigPrefs panel. class KeyConfigPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/LibraryPrefs.h b/src/prefs/LibraryPrefs.h index 195928c3c..991d1dfee 100644 --- a/src/prefs/LibraryPrefs.h +++ b/src/prefs/LibraryPrefs.h @@ -47,6 +47,7 @@ class LibraryPrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one LibraryPrefs panel. class LibraryPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/MidiIOPrefs.h b/src/prefs/MidiIOPrefs.h index 693577bc0..df1d36d12 100644 --- a/src/prefs/MidiIOPrefs.h +++ b/src/prefs/MidiIOPrefs.h @@ -63,6 +63,7 @@ class MidiIOPrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one MidiIOPrefs panel. class MidiIOPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/ModulePrefs.h b/src/prefs/ModulePrefs.h index d67a5fdca..33b39b835 100644 --- a/src/prefs/ModulePrefs.h +++ b/src/prefs/ModulePrefs.h @@ -51,6 +51,7 @@ class ModulePrefs final : public PrefsPanel wxArrayString mPaths; }; +/// A PrefsPanelFactory that creates one ModulePrefs panel. class ModulePrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/MousePrefs.h b/src/prefs/MousePrefs.h index 52e2aa414..e71ee2592 100644 --- a/src/prefs/MousePrefs.h +++ b/src/prefs/MousePrefs.h @@ -39,6 +39,7 @@ class MousePrefs final : public PrefsPanel wxListCtrl * mList; }; +/// A PrefsPanelFactory that creates one MousePrefs panel. class MousePrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/PlaybackPrefs.h b/src/prefs/PlaybackPrefs.h index ffc4c4e76..818965041 100644 --- a/src/prefs/PlaybackPrefs.h +++ b/src/prefs/PlaybackPrefs.h @@ -35,6 +35,8 @@ class PlaybackPrefs final : public PrefsPanel void Populate(); }; + +/// A PrefsPanelFactory that creates one PlaybackPrefs panel. class PlaybackPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/PrefsPanel.h b/src/prefs/PrefsPanel.h index ce6f18bd4..5a1f1baa0 100644 --- a/src/prefs/PrefsPanel.h +++ b/src/prefs/PrefsPanel.h @@ -9,10 +9,9 @@ *******************************************************************//** \class PrefsPanel -\brief Used within the PrefsDialog, classes derived from this class -include AudioIOPrefs, BatchPrefs, DirectoriesPrefs, FileFormatPrefs, -GUIPrefs, KeyConfigPrefs, MousePrefs, QualityPrefs, SpectrumPrefs and -ThemePrefs. +\brief Base class for a panel in the PrefsDialog. Classes derived from +this class include BatchPrefs, DirectoriesPrefs, GUIPrefs, KeyConfigPrefs, +MousePrefs, QualityPrefs, SpectrumPrefs and ThemePrefs. The interface works like this: Each panel in the preferences dialog must derive from PrefsPanel. You must override Apply() with code @@ -20,9 +19,15 @@ ThemePrefs. global preferences object gPrefs, and instructing the applicable parts of the program to re-read the preference options. - To actually add a the NEW panel, edit the PrefsDialog constructor + To actually add the new panel, edit the PrefsDialog constructor to append the panel to its list of panels. +*******************************************************************//** + +\class PrefsPanelFactory +\brief Base class for factories such as GUIPrefsFactory that produce a +PrefsPanel. + *//*******************************************************************/ #ifndef __AUDACITY_PREFS_PANEL__ diff --git a/src/prefs/ProjectsPrefs.h b/src/prefs/ProjectsPrefs.h index 750a7fb9e..34a6a1517 100644 --- a/src/prefs/ProjectsPrefs.h +++ b/src/prefs/ProjectsPrefs.h @@ -34,6 +34,7 @@ class ProjectsPrefs final : public PrefsPanel void Populate(); }; +/// A PrefsPanelFactory that creates one ProjectPrefs panel. class ProjectsPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/QualityPrefs.h b/src/prefs/QualityPrefs.h index 8efae6a36..c44119f06 100644 --- a/src/prefs/QualityPrefs.h +++ b/src/prefs/QualityPrefs.h @@ -55,6 +55,7 @@ class QualityPrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one QualityPrefs panel. class QualityPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/RecordingPrefs.h b/src/prefs/RecordingPrefs.h index 7f015f1bf..be179994c 100644 --- a/src/prefs/RecordingPrefs.h +++ b/src/prefs/RecordingPrefs.h @@ -41,6 +41,7 @@ class RecordingPrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one RecordingPrefs panel. class RecordingPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/SpectrumPrefs.h b/src/prefs/SpectrumPrefs.h index 3de188f65..7c6ddf96f 100644 --- a/src/prefs/SpectrumPrefs.h +++ b/src/prefs/SpectrumPrefs.h @@ -104,6 +104,7 @@ class SpectrumPrefs final : public PrefsPanel bool mCommitted{}; }; +/// A PrefsPanelFactory that creates one SpectrumPrefs panel. class SpectrumPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/ThemePrefs.h b/src/prefs/ThemePrefs.h index 10668ee8e..1f1271b89 100644 --- a/src/prefs/ThemePrefs.h +++ b/src/prefs/ThemePrefs.h @@ -41,6 +41,7 @@ class ThemePrefs final : public PrefsPanel DECLARE_EVENT_TABLE() }; +/// A PrefsPanelFactory that creates one ThemePrefs panel. class ThemePrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/TracksBehaviorsPrefs.h b/src/prefs/TracksBehaviorsPrefs.h index 332c25ec2..e281ecdc4 100644 --- a/src/prefs/TracksBehaviorsPrefs.h +++ b/src/prefs/TracksBehaviorsPrefs.h @@ -37,6 +37,7 @@ class TracksBehaviorsPrefs final : public PrefsPanel wxArrayString mSoloChoices; }; +/// A PrefsPanelFactory that creates one TracksBehaviorsPrefs panel. class TracksBehaviorsPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/TracksPrefs.h b/src/prefs/TracksPrefs.h index 4c56d3c25..2777e22ad 100644 --- a/src/prefs/TracksPrefs.h +++ b/src/prefs/TracksPrefs.h @@ -52,6 +52,7 @@ class TracksPrefs final : public PrefsPanel static int iPreferencePinned; }; +/// A PrefsPanelFactory that creates one TracksPrefs panel. class TracksPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/WarningsPrefs.h b/src/prefs/WarningsPrefs.h index 8b9fa4b6f..18952cf01 100644 --- a/src/prefs/WarningsPrefs.h +++ b/src/prefs/WarningsPrefs.h @@ -34,6 +34,7 @@ class WarningsPrefs final : public PrefsPanel void PopulateOrExchange(ShuttleGui & S) override; }; +/// A PrefsPanelFactory that creates one WarningPrefs panel. class WarningsPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/prefs/WaveformPrefs.h b/src/prefs/WaveformPrefs.h index 77a627ce6..af25fbcec 100644 --- a/src/prefs/WaveformPrefs.h +++ b/src/prefs/WaveformPrefs.h @@ -56,6 +56,7 @@ private: bool mPopulating; }; +/// A PrefsPanelFactory that creates one WaveformPrefs panel. class WaveformPrefsFactory final : public PrefsPanelFactory { public: diff --git a/src/tracks/ui/BackgroundCell.h b/src/tracks/ui/BackgroundCell.h index cdd3bf028..dfa4f86fa 100644 --- a/src/tracks/ui/BackgroundCell.h +++ b/src/tracks/ui/BackgroundCell.h @@ -19,6 +19,9 @@ class AudacityProject; class BackgroundHandle; class ZoomHandle; + +/// \brief Class representing the background of a Track. It +/// provides the hit test function that tells us what was hit. class BackgroundCell final : public CommonTrackPanelCell { public: diff --git a/src/tracks/ui/ButtonHandle.h b/src/tracks/ui/ButtonHandle.h index fa983a3cf..9aaf34278 100644 --- a/src/tracks/ui/ButtonHandle.h +++ b/src/tracks/ui/ButtonHandle.h @@ -20,6 +20,9 @@ class wxMouseState; class Track; + +/// \brief A UIHandle for a TrackPanel button, such as the Mute and Solo +/// buttons. class ButtonHandle /* not final */ : public UIHandle { ButtonHandle(const ButtonHandle&) = delete; diff --git a/src/widgets/BackedPanel.h b/src/widgets/BackedPanel.h index a9faf78a9..4e262e0fa 100644 --- a/src/widgets/BackedPanel.h +++ b/src/widgets/BackedPanel.h @@ -13,6 +13,10 @@ #include #include "wxPanelWrapper.h" + +/// \brief BackedPanel is for a panel that consists of a bitmap with something drawn +/// obver it. It supports efficient repainting when the overlays change and +/// recreation of the bitmap when the panel size is changed. class AUDACITY_DLL_API BackedPanel /* not final */ : public wxPanelWrapper { public: BackedPanel(wxWindow * parent, wxWindowID id, diff --git a/src/widgets/Grabber.h b/src/widgets/Grabber.h index 53d23904d..b232b22c4 100644 --- a/src/widgets/Grabber.h +++ b/src/widgets/Grabber.h @@ -18,6 +18,12 @@ \brief The widget to the left of a ToolBar that allows it to be dragged around to NEW positions. +*//*******************************************************************//** + +\class AStaticBitmap +\brief A widget for bitmaps which ignores the erase event for +flicker-free use. + *//**********************************************************************/ #ifndef __AUDACITY_WIDGETS_GRABBER__ diff --git a/src/widgets/Grid.h b/src/widgets/Grid.h index 84c25fc6d..f148feb92 100644 --- a/src/widgets/Grid.h +++ b/src/widgets/Grid.h @@ -33,11 +33,12 @@ class GridAx; class NumericTextCtrl; using NumericFormatId = ComponentInterfaceSymbol; -// ---------------------------------------------------------------------------- -// NumericEditor -// -// wxGridCellEditor for the NumericTextCtrl. -// ---------------------------------------------------------------------------- +/**********************************************************************//** + +\class NumericEditor +\brief wxGridCellEditor for the NumericTextCtrl. + +**************************************************************************/ #define GRID_VALUE_TIME wxT("Time") #define GRID_VALUE_FREQUENCY wxT("Frequency") @@ -86,12 +87,10 @@ public: wxString mValueAsString; }; -// ---------------------------------------------------------------------------- -// NumericRenderer -// -// wxGridCellRenderer for the NumericTextCtrl. -// ---------------------------------------------------------------------------- - +/**********************************************************************//** +\class NumericRenderer +\brief wxGridCellRenderer for the NumericTextCtrl. +**************************************************************************/ class NumericRenderer final : public wxGridCellRenderer { public: @@ -118,11 +117,11 @@ private: NumericConverter::Type mType; }; -// ---------------------------------------------------------------------------- -// ChoiceEditor -// -// Modified version of wxGridChoiceEditor using wxChoice instead of wxComboBox. -// ---------------------------------------------------------------------------- +/**********************************************************************//** +\class ChoiceEditor +\brief Modified version of wxGridChoiceEditor using wxChoice instead of +wxComboBox. +**************************************************************************/ #define GRID_VALUE_CHOICE wxT("Choice") class ChoiceEditor final : public wxGridCellEditor, wxEvtHandler @@ -184,11 +183,10 @@ public: wxString mValueAsString; }; -// ---------------------------------------------------------------------------- -// Grid -// -// wxGrid with support for accessibility. -// ---------------------------------------------------------------------------- +/**********************************************************************//** +\class Grid +\brief wxGrid with support for accessibility. +**************************************************************************/ class Grid final : public wxGrid { @@ -236,12 +234,10 @@ class Grid final : public wxGrid }; #if wxUSE_ACCESSIBILITY -// ---------------------------------------------------------------------------- -// GridAx -// -// wxAccessible object providing grid information for Grid. -// ---------------------------------------------------------------------------- - +/**********************************************************************//** +\class GridAx +\brief wxAccessible object providing grid information for Grid. +**************************************************************************/ class GridAx final : public WindowAccessible { diff --git a/src/widgets/LinkingHtmlWindow.h b/src/widgets/LinkingHtmlWindow.h index c84fd7aff..dd8f5abe7 100644 --- a/src/widgets/LinkingHtmlWindow.h +++ b/src/widgets/LinkingHtmlWindow.h @@ -24,6 +24,10 @@ void OpenInDefaultBrowser(const wxHtmlLinkInfo& link); + +/// \brief An HtmlWindow that handles linked clicked - usually the +/// link will go to our own local copy of the manual, but it could +/// launch a new browser window. class AUDACITY_DLL_API LinkingHtmlWindow final : public HtmlWindow { public: @@ -36,6 +40,8 @@ class AUDACITY_DLL_API LinkingHtmlWindow final : public HtmlWindow }; + +/// Adds some event handling to an HtmlWindow class BrowserDialog /* not final */ : public wxDialogWrapper { public: