audacia
/
audacia
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

More doxygen

This commit is contained in:
James Crook 2018-11-04 14:19:05 +00:00
parent 648d7ddb73
commit b5d4a828d1
8 changed files with 96 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
src/AudacityException.h
View File

@ -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

3
src/FFmpeg.h
View File

@ -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>
>

2
src/Lyrics.h
View File

@ -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;

93
src/MemoryX.h
View File

@ -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> {

13
src/TrackPanel.cpp
View File

@ -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

2
src/TrackPanelCell.h
View File

@ -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

2
src/effects/Paulstretch.cpp
View File

@ -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:

3
src/toolbars/ToolBar.cpp
View File

@ -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: