More doxygen

src/AudacityException.h

@@ -41,10 +41,10 @@ protected:
    AudacityException &operator = ( const AudacityException & ) PROHIBITED;
 };
 
-// A subclass of AudacityException whose delayed handler action displays
-// a message box.  The message is specified by further subclasses.
-// Not more than one message box will be displayed for each pass through
-// the main event idle loop.
+/// \brief A subclass of AudacityException whose delayed handler action displays
+/// a message box.  The message is specified by further subclasses.
+/// Not more than one message box will be displayed for each pass through
+/// the main event idle loop.
 class MessageBoxException /* not final */ : public AudacityException
 {
    // Do not allow subclasses to change this behavior further, except
@@ -68,7 +68,7 @@ private:
    mutable bool moved { false };
 };
 
-// MessageBoxException that shows a given, unvarying string.
+/// \brief A MessageBoxException that shows a given, unvarying string.
 class SimpleMessageBoxException /* not final */ : public MessageBoxException
 {
 public:
@@ -90,6 +90,8 @@ private:
    wxString message;
 };
 
+
+/// \brief performs the delayed configured action, when invoked.
 struct DefaultDelayedHandlerAction
 {
    void operator () (AudacityException *pException) const
@@ -99,8 +101,8 @@ struct DefaultDelayedHandlerAction
    }
 };
 
-// Classes that can supply the second argument of GuardedCall:
-// Frequently useful converter of all exceptions to some failure constant
+/// \brief SimpleGuard classes add the second argument of GuardedCall:
+/// Frequently useful converter of all exceptions to some failure constant
 template <typename R> struct SimpleGuard
 {
    explicit SimpleGuard( R value ) : m_value{ value } {}
@@ -108,7 +110,7 @@ template <typename R> struct SimpleGuard
    const R m_value;
 };
 
-// Simple guard specialization that returns bool, and defines Default
+/// \brief SimpleGuard specialization that returns bool, and defines Default
 template<> struct SimpleGuard<bool>
 {
    explicit SimpleGuard( bool value ) : m_value{ value } {}
@@ -118,7 +120,7 @@ template<> struct SimpleGuard<bool>
    const bool m_value;
 };
 
-// Simple guard specialization that returns nothing, and defines Default
+/// \brief SimpleGuard specialization that returns nothing, and defines Default
 template<> struct SimpleGuard<void>
 {
    SimpleGuard() {}
@@ -132,16 +134,24 @@ SimpleGuard< R > MakeSimpleGuard( R value )
 
 inline SimpleGuard< void > MakeSimpleGuard() { return {}; }
 
-/**
- * Call the body function (usually a lambda) inside a try block.
- *
- * The handler intercepts exceptions, and is passed nullptr if the
- * exception is of a type not defined by Audacity.  It may return a value
- * for the guarded call or throw the same or another exception.
- * It executes in the same thread as the body.
- *
- * If the handler is passed non-null and does not throw, then delayedHandler
- * executes later in the main thread, in idle time of the event loop.
+/***
+  \brief GuardedCall performs a body action, and provided there is no 
+  exception a handler action on completion.  If there is an exception, 
+  it queues up the delayed handler action for execution later in 
+  the idle event loop
+
+  The template is rather configurable, and default behaviours can be 
+  overridden.  GuardedCall makes use of SimpleGuard for the handler action.
+
+  GuardedCall calls the body function (usually a lambda) inside a try block.
+ 
+  The handler intercepts exceptions, and is passed nullptr if the
+  exception is of a type not defined by Audacity.  It may return a value
+  for the guarded call or throw the same or another exception.
+  The handler executes in the same thread as the body.
+ 
+  If the handler is passed non-null and does not throw, then delayedHandler
+  executes later in the main thread, in idle time of the event loop.
  */
 template <
    typename R = void, // return type

src/FFmpeg.h

@@ -999,6 +999,9 @@ using AVCodecContextHolder = std::unique_ptr<
 using AVDictionaryCleanup = std::unique_ptr<
    AVDictionary*, AV_Deleter<AVDictionary*, void, av_dict_free>
 >;
+
+/// \brief FFmpeg structure to hold a file pointer and provide a return 
+/// value when closing the file.
 struct UFileHolder : public std::unique_ptr<
    AVIOContext, ::AV_Deleter<AVIOContext, int, ufile_close>
 >

src/Lyrics.h

@@ -25,6 +25,8 @@ class LabelTrack;
 #define LYRICS_DEFAULT_WIDTH 608
 #define LYRICS_DEFAULT_HEIGHT 280
 
+/// \brief used in LyricsPanel, a Syllable gives positional information to
+/// be used with the bouncing ball effect.
 struct Syllable {
    Syllable() = default;
    Syllable( const Syllable& ) = default;

src/MemoryX.h

@@ -123,11 +123,14 @@ public:
    }
 };
 
-/*
- * ArraysOf<X>
- * This simplifies arrays of arrays, each array separately allocated with NEW[]
- * But it might be better to use std::Array<ArrayOf<X>, N> for some small constant N
- * Or use just one array when sub-arrays have a common size and are not large.
+/**
+  \class ArrayOf
+
+  ArraysOf<X>
+
+  \brief This simplifies arrays of arrays, each array separately allocated with NEW[]
+  But it might be better to use std::Array<ArrayOf<X>, N> for some small constant N
+  Or use just one array when sub-arrays have a common size and are not large.
  */
 template<typename X>
 class ArraysOf : public ArrayOf<ArrayOf<X>>
@@ -181,12 +184,15 @@ public:
    }
 };
 
-/*
- * template class Maybe<X>
- * Can be used for monomorphic objects that are stack-allocable, but only conditionally constructed.
- * You might also use it as a member.
- * Initialize with create(), then use like a smart pointer,
- * with *, ->, get(), reset(), or in if()
+/**
+  \class Maybe
+  \brief Like a smart pointer, allows for object to not exist (nullptr)
+
+  template class Maybe<X>
+  Can be used for monomorphic objects that are stack-allocable, but only conditionally constructed.
+  You might also use it as a member.
+  Initialize with create(), then use like a smart pointer,
+  with *, ->, get(), reset(), or in if()
  */
 
 // Placement-NEW is used below, and that does not cooperate with the DEBUG_NEW for Visual Studio
@@ -196,6 +202,7 @@ public:
 #endif
 #endif
 
+
 template<typename X>
 class Maybe {
 public:
@@ -238,11 +245,11 @@ public:
       return *this;
    }
 
-   // Make an object in the buffer, passing constructor arguments,
-   // but destroying any previous object first
-   // Note that if constructor throws, we remain in a consistent
-   // NULL state -- giving exception safety but only weakly
-   // (previous value was lost if present)
+   /// Make an object in the buffer, passing constructor arguments,
+   /// but destroying any previous object first
+   /// Note that if constructor throws, we remain in a consistent
+   /// NULL state -- giving exception safety but only weakly
+   /// (previous value was lost if present)
    template<typename... Args>
    void create(Args&&... args)
    {
@@ -260,7 +267,7 @@ public:
 
    // Pointer-like operators
 
-   // Dereference, with the usual bad consequences if NULL
+   /// Dereference, with the usual bad consequences if NULL
    X &operator* () const
    {
       return *pp;
@@ -318,44 +325,44 @@ static char*THIS_FILE = __FILE__;
 #endif
 #endif
 
-/*
- * A deleter for pointers obtained with malloc
+/**
+  A deleter for pointers obtained with malloc
  */
 struct freer { void operator() (void *p) const { free(p); } };
 
-/*
- * A useful alias for holding the result of malloc
+/**
+  A useful alias for holding the result of malloc
  */
 template< typename T >
 using MallocPtr = std::unique_ptr< T, freer >;
 
-/*
- * A useful alias for holding the result of strup and similar
+/**
+  A useful alias for holding the result of strup and similar
  */
 template <typename Character = char>
 using MallocString = std::unique_ptr< Character[], freer >;
 
-/*
- * A deleter class to supply the second template parameter of unique_ptr for
- * classes like wxWindow that should be sent a message called Destroy rather
- * than be deleted directly
+/**
+  \brief A deleter class to supply the second template parameter of unique_ptr for
+  classes like wxWindow that should be sent a message called Destroy rather
+  than be deleted directly
  */
 template <typename T>
 struct Destroyer {
    void operator () (T *p) const { if (p) p->Destroy(); }
 };
 
-/*
- * a convenience for using Destroyer
+/**
+  \brief a convenience for using Destroyer
  */
 template <typename T>
 using Destroy_ptr = std::unique_ptr<T, Destroyer<T>>;
 
-/*
- * "finally" as in The C++ Programming Language, 4th ed., p. 358
- * Useful for defining ad-hoc RAII actions.
- * typical usage:
- * auto cleanup = finally([&]{ ... code; ... });
+/**
+  \brief "finally" as in The C++ Programming Language, 4th ed., p. 358
+  Useful for defining ad-hoc RAII actions.
+  typical usage:
+  auto cleanup = finally([&]{ ... code; ... });
  */
 
 // Construct this from any copyable function object, such as a lambda
@@ -366,8 +373,8 @@ struct Final_action {
    F clean;
 };
 
-// Function template with type deduction lets you construct Final_action
-// without typing any angle brackets
+/// \brief Function template with type deduction lets you construct Final_action
+/// without typing any angle brackets
 template <typename F>
 Final_action<F> finally (F f)
 {
@@ -377,8 +384,8 @@ Final_action<F> finally (F f)
 #include <wx/utils.h> // for wxMin, wxMax
 #include <algorithm>
 
-/*
- * Set a variable temporarily in a scope
+/**
+  \brief Structure used by ValueRestorer 
  */
 template< typename T >
 struct RestoreValue {
@@ -386,6 +393,10 @@ struct RestoreValue {
    void operator () ( T *p ) const { if (p) *p = oldValue; }
 };
 
+
+/**
+  \brief Set a variable temporarily in a scope
+  */
 template< typename T >
 class ValueRestorer : public std::unique_ptr< T, RestoreValue<T> >
 {
@@ -408,7 +419,7 @@ public:
    }
 };
 
-// inline functions provide convenient parameter type deduction
+/// inline functions provide convenient parameter type deduction
 template< typename T >
 ValueRestorer< T > valueRestorer( T& var )
 { return ValueRestorer< T >{ var }; }
@@ -417,8 +428,8 @@ template< typename T >
 ValueRestorer< T > valueRestorer( T& var, const T& newValue )
 { return ValueRestorer< T >{ var, newValue }; }
 
-/*
- * A convenience for use with range-for
+/**
+  \brief A convenience for use with range-for
  */
 template <typename Iterator>
 struct IteratorRange : public std::pair<Iterator, Iterator> {

src/TrackPanel.cpp

@@ -15,14 +15,7 @@
 \brief
   Implements TrackPanel and TrackInfo.
 
-*//********************************************************************/
-
-// Documentation: Rather than have a lengthy \todo section, having
-// a \todo a \file and a \page in EXACTLY that order gets Doxygen to
-// put the following lengthy description of refactoring on a NEW page
-// and link to it from the docs.
-
-/*****************************************************************//**
+*//***************************************************************//**
 
 \class TrackPanel
 \brief
@@ -100,7 +93,9 @@ is time to refresh some aspect of the screen.
 
 wxDEFINE_EVENT(EVT_TRACK_PANEL_TIMER, wxCommandEvent);
 
-/*
+/**
+
+\class TrackPanel
 
 This is a diagram of TrackPanel's division of one (non-stereo) track rectangle.
 Total height equals Track::GetHeight()'s value.  Total width is the wxWindow's

src/TrackPanelCell.h

@@ -28,7 +28,7 @@ using UIHandlePtr = std::shared_ptr<UIHandle>;
 
 #include <vector>
 
-/// The TrackPanel is built up of nodes, subtrees of the CellularPanel's area
+/// \brief 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

src/effects/Paulstretch.cpp

@@ -39,6 +39,8 @@
 Param( Amount, float,   wxT("Stretch Factor"),   10.0,    1.0,     FLT_MAX, 1   );
 Param( Time,   float,   wxT("Time Resolution"),  0.25f,   0.00099f,  FLT_MAX, 1   );
 
+/// \brief Class that helps EffectPaulStretch.  It does the FFTs and inner loop 
+/// of the effect.
 class PaulStretch
 {
 public:

src/toolbars/ToolBar.cpp

@@ -64,6 +64,9 @@ in which buttons can be placed.
 //
 #define RWIDTH 4
 
+/// \brief a wxWindow that provides the resizer for a toolbar on the 
+/// right hand side.  Responsible for drawing the resizer appearance, 
+/// resizing mouse events and constraining the resizing.
 class ToolBarResizer final : public wxWindow
 {
 public: