From bef951a5820197c887927e66d49107ac2d2684a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 11 May 2014 17:26:22 +0200 Subject: [PATCH] Audio: completed documentation review. --- src/Magnum/Audio/AbstractImporter.h | 43 +++++++++++++++-------------- src/Magnum/Audio/Audio.h | 2 +- src/Magnum/Audio/Buffer.h | 4 +-- src/Magnum/Audio/Context.h | 8 +++--- src/Magnum/Audio/Renderer.h | 8 +++--- src/Magnum/Audio/Source.h | 8 +++--- 6 files changed, 37 insertions(+), 36 deletions(-) diff --git a/src/Magnum/Audio/AbstractImporter.h b/src/Magnum/Audio/AbstractImporter.h index 2307bb262..40c388138 100644 --- a/src/Magnum/Audio/AbstractImporter.h +++ b/src/Magnum/Audio/AbstractImporter.h @@ -25,8 +25,8 @@ DEALINGS IN THE SOFTWARE. */ -/** @file Audio/AbstractImporter.h - * @brief Class Magnum::Audio::AbstractImporter +/** @file + * @brief Class @ref Magnum::Audio::AbstractImporter */ #include @@ -45,16 +45,17 @@ importer plugins. @section Audio-AbstractImporter-subclassing Subclassing -Plugin implements function doFeatures(), doIsOpened(), one of or both -doOpenData() and doOpenFile() functions, function doClose() and data access -functions doFormat(), doFrequency() and doData(). +Plugin implements function @ref doFeatures(), @ref doIsOpened(), one of or both +@ref doOpenData() and @ref doOpenFile() functions, function @ref doClose() and +data access functions @ref doFormat(), @ref doFrequency() and @ref doData(). You don't need to do most of the redundant sanity checks, these things are checked by the implementation: -- Functions doOpenData() and doOpenFile() are called after the previous file - was closed, function doClose() is called only if there is any file opened. -- Function doOpenData() is called only if @ref Feature::OpenData is +- Functions @ref doOpenData() and @ref doOpenFile() are called after the + previous file was closed, function @ref doClose() is called only if there + is any file opened. +- Function @ref doOpenData() is called only if @ref Feature::OpenData is supported. - All `do*()` implementations working on opened file are called only if there is any file opened. @@ -66,17 +67,17 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractPlugin /** * @brief Features supported by this importer * - * @see Features, features() + * @see @ref Features, @ref features() */ enum class Feature: UnsignedByte { - /** Opening files from raw data using openData() */ + /** Opening files from raw data using @ref openData() */ OpenData = 1 << 0 }; /** * @brief Features supported by this importer * - * @see features() + * @see @ref features() */ typedef Containers::EnumSet Features; @@ -98,7 +99,7 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractPlugin * Closes previous file, if it was opened, and tries to open given * file. Available only if @ref Feature::OpenData is supported. Returns * `true` on success, `false` otherwise. - * @see features(), openFile() + * @see @ref features(), @ref openFile() */ bool openData(Containers::ArrayReference data); @@ -107,7 +108,7 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractPlugin * * Closes previous file, if it was opened, and tries to open given * file. Returns `true` on success, `false` otherwise. - * @see features(), openData() + * @see @ref features(), @ref openData() */ bool openFile(const std::string& filename); @@ -132,33 +133,33 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractPlugin #else protected: #endif - /** @brief Implementation for features() */ + /** @brief Implementation for @ref features() */ virtual Features doFeatures() const = 0; - /** @brief Implementation for isOpened() */ + /** @brief Implementation for @ref isOpened() */ virtual bool doIsOpened() const = 0; - /** @brief Implementation for openData() */ + /** @brief Implementation for @ref openData() */ virtual void doOpenData(Containers::ArrayReference data); /** - * @brief Implementation for openFile() + * @brief Implementation for @ref openFile() * * If @ref Feature::OpenData is supported, default implementation opens * the file and calls @ref doOpenData() with its contents. */ virtual void doOpenFile(const std::string& filename); - /** @brief Implementation for close() */ + /** @brief Implementation for @ref close() */ virtual void doClose() = 0; - /** @brief Implementation for format() */ + /** @brief Implementation for @ref format() */ virtual Buffer::Format doFormat() const = 0; - /** @brief Implementation for frequency() */ + /** @brief Implementation for @ref frequency() */ virtual UnsignedInt doFrequency() const = 0; - /** @brief Implementation for data() */ + /** @brief Implementation for @ref data() */ virtual Containers::Array doData() = 0; }; diff --git a/src/Magnum/Audio/Audio.h b/src/Magnum/Audio/Audio.h index 72ba9e27a..46865200d 100644 --- a/src/Magnum/Audio/Audio.h +++ b/src/Magnum/Audio/Audio.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Forward declarations for Magnum::Audio namespace + * @brief Forward declarations for @ref Magnum::Audio namespace */ namespace Magnum { namespace Audio { diff --git a/src/Magnum/Audio/Buffer.h b/src/Magnum/Audio/Buffer.h index f42829334..de7147355 100644 --- a/src/Magnum/Audio/Buffer.h +++ b/src/Magnum/Audio/Buffer.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Audio::Buffer + * @brief Class @ref Magnum::Audio::Buffer */ #include @@ -104,7 +104,7 @@ class Buffer { ALuint _id; }; -/** @debugoperator{Magnum::Audio::Buffer} */ +/** @debugoperatorclassenum{Magnum::Audio::Buffer,Magnum::Audio::Buffer::Format} */ Debug MAGNUM_AUDIO_EXPORT operator<<(Debug debug, Buffer::Format value); inline Buffer::Buffer(Buffer&& other): _id(other._id) { diff --git a/src/Magnum/Audio/Context.h b/src/Magnum/Audio/Context.h index 1864f9c91..2ef9c37d5 100644 --- a/src/Magnum/Audio/Context.h +++ b/src/Magnum/Audio/Context.h @@ -25,8 +25,8 @@ DEALINGS IN THE SOFTWARE. */ -/** @file Audio/Context.h - * @brief Class Magnum::Audio::Context +/** @file + * @brief Class @ref Magnum::Audio::Context */ #include @@ -66,14 +66,14 @@ class MAGNUM_AUDIO_EXPORT Context { /** * @brief Vendor string * - * @see rendererString(), @fn_al{GetString} with @def_al{VENDOR} + * @see @ref rendererString(), @fn_al{GetString} with @def_al{VENDOR} */ std::string vendorString() const { return alGetString(AL_VENDOR); } /** * @brief %Renderer string * - * @see vendorString(), @fn_al{GetString} with @def_al{RENDERER} + * @see @ref vendorString(), @fn_al{GetString} with @def_al{RENDERER} */ std::string rendererString() const { return alGetString(AL_RENDERER); } diff --git a/src/Magnum/Audio/Renderer.h b/src/Magnum/Audio/Renderer.h index ca31f9bbe..c70969c8e 100644 --- a/src/Magnum/Audio/Renderer.h +++ b/src/Magnum/Audio/Renderer.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Audio::Renderer + * @brief Class @ref Magnum::Audio::Renderer */ #include @@ -45,7 +45,7 @@ class Renderer { /** * @brief Error status * - * @see error() + * @see @ref error() */ enum class Error: ALenum { NoError = AL_NO_ERROR, /**< No error occured */ @@ -116,7 +116,7 @@ class Renderer { /** * @brief Distance model * - * @see setDistanceModel() + * @see @ref setDistanceModel() */ enum class DistanceModel: ALenum { /** No distance attenuation calculation */ @@ -185,7 +185,7 @@ class Renderer { /*@}*/ }; -/** @debugoperator{Magnum::Audio::Renderer} */ +/** @debugoperatorclassenum{Magnum::Audio::Renderer,Magnum::Audio::Renderer::Error} */ Debug MAGNUM_AUDIO_EXPORT operator<<(Debug debug, Renderer::Error value); inline void Renderer::setListenerOrientation(const Vector3& forward, const Vector3& up) { diff --git a/src/Magnum/Audio/Source.h b/src/Magnum/Audio/Source.h index 2c9402f15..ff5b3ae29 100644 --- a/src/Magnum/Audio/Source.h +++ b/src/Magnum/Audio/Source.h @@ -26,7 +26,7 @@ */ /** @file - * @brief Class Magnum::Audio::Source + * @brief Class @ref Magnum::Audio::Source */ #include @@ -338,7 +338,7 @@ class MAGNUM_AUDIO_EXPORT Source { }; /** - * @brief Source type + * @brief %Source type * * @see @ref setBuffer(), @fn_al{GetSourcei} with @def_al{SOURCE_TYPE} */ @@ -346,7 +346,7 @@ class MAGNUM_AUDIO_EXPORT Source { /** * @brief Attach buffer - * @param buffer Buffer to attach or `nullptr` + * @param buffer %Buffer to attach or `nullptr` * @return Reference to self (for method chaining) * * If an buffer is attached, changes source type to @ref Type::Static, @@ -586,7 +586,7 @@ class MAGNUM_AUDIO_EXPORT Source { ALuint _id; }; -/** @debugoperator{Magnum::Audio::Source} */ +/** @debugoperatorclassenum{Magnum::Audio::Source,Magnum::Audio::Source::State} */ Debug MAGNUM_AUDIO_EXPORT operator<<(Debug debug, Source::State value); inline Source::Source(Source&& other): _id(other._id) {