More doxygen

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<typename T, typename R, R(*Fn)(T*)> struct AV_Deleter {
    inline R operator() (T* p) const
    {

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() {}

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& );

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:

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<typename, TrackKind> struct Pair;
    using List = std::tuple<
@@ -160,12 +160,13 @@ template<typename T>
 
 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:

src/TrackPanelCell.h

@@ -28,7 +28,9 @@ using UIHandlePtr = std::shared_ptr<UIHandle>;
 
 #include <vector>
 
-// 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:

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();

src/menus/ClipMenus.cpp

@@ -726,6 +726,7 @@ void DoClipLeftOrRight
 
 }
 
+/// Namespace for functions for Clip menu
 namespace ClipActions {
 
 // exported helper functions

src/menus/ExtraMenus.cpp

@@ -9,6 +9,7 @@
 namespace {
 }
 
+/// Namespace for helper functions for Extra menu
 namespace ExtraActions {
 
 // exported helper functions

src/menus/LabelMenus.cpp

@@ -242,6 +242,7 @@ void EditClipboardByLabel(
 
 }
 
+/// Namespace for functions for Edit Label submenu
 namespace LabelEditActions {
 
 // exported helper functions

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

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

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

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"

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:

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:

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:

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:

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:

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:

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:

src/prefs/KeyConfigPrefs.h

@@ -94,6 +94,7 @@ private:
 };
 
 
+/// A PrefsPanelFactory that creates one KeyConfigPrefs panel.
 class KeyConfigPrefsFactory final : public PrefsPanelFactory
 {
 public:

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:

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:

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:

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:

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:

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__

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:

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:

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:

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:

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:

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:

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:

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:

src/prefs/WaveformPrefs.h

@@ -56,6 +56,7 @@ private:
    bool mPopulating;
 };
 
+/// A PrefsPanelFactory that creates one WaveformPrefs panel.
 class WaveformPrefsFactory final : public PrefsPanelFactory
 {
 public:

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:

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;

src/widgets/BackedPanel.h

@@ -13,6 +13,10 @@
 #include <wx/dcmemory.h>
 #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,

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__

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
 {
 

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: