From 87c3d8a0d99c132546414e889f415c81e6ec939f Mon Sep 17 00:00:00 2001 From: Martijn van Beurden Date: Sat, 17 Sep 2022 21:46:07 +0200 Subject: Fix a lot of Doxygen errors and add some documentation --- doc/Doxyfile.in | 4 ++-- include/FLAC++/export.h | 27 +++++++++++++++++---------- include/FLAC/callback.h | 12 ++++++------ include/FLAC/export.h | 17 ++++++++++++++--- 4 files changed, 39 insertions(+), 21 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 8a1a159e..d3533e75 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -193,8 +193,8 @@ TAB_SIZE = 4 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = "assert=\par Assertions:\n" \ - "default=\par Default Value:\n" +ALIASES = "assert=\par Assertions:" \ + "default=\par Default Value:" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding diff --git a/include/FLAC++/export.h b/include/FLAC++/export.h index e672e8f0..19370fab 100644 --- a/include/FLAC++/export.h +++ b/include/FLAC++/export.h @@ -49,20 +49,30 @@ * This module contains \#defines and symbols for exporting function * calls, and providing version information and compiled-in features. * - * If you are compiling with MSVC and will link to the static library - * (libFLAC++.lib) you should define FLAC__NO_DLL in your project to - * make sure the symbols are exported properly. + * If you are compiling for Windows (with Visual Studio or MinGW for + * example) and will link to the static library (libFLAC++.lib) you + * should define FLAC__NO_DLL in your project to make sure the symbols + * are exported properly. * * \{ */ +/** This \#define is used internally in libFLAC and its headers to make + * sure the correct symbols are exported when working with shared + * libraries. On Windows, this \#define is set to __declspec(dllexport) + * when compiling libFLAC into a library and to __declspec(dllimport) + * when the headers are used to link to that DLL. On non-Windows systems + * it is used to set symbol visibility. + * + * Because of this, the define FLAC__NO_DLL must be defined when linking + * to libFLAC statically or linking will fail. + */ /* This has grown quite complicated. FLAC__NO_DLL is used by MSVC sln * files and CMake, which build either static or shared. autotools can * build static, shared or **both**. Therefore, DLL_EXPORT, which is set * by libtool, must override FLAC__NO_DLL on building shared components */ #if defined(_WIN32) - #if defined(FLAC__NO_DLL) && !(defined(DLL_EXPORT)) #define FLACPP_API #else @@ -72,21 +82,18 @@ #define FLACPP_API __declspec(dllimport) #endif #endif - #elif defined(FLAC__USE_VISIBILITY_ATTR) #define FLACPP_API __attribute__ ((visibility ("default"))) - #else #define FLACPP_API - #endif -/* These \#defines will mirror the libtool-based library version number, see +/** These \#defines will mirror the libtool-based library version number, see * http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning */ #define FLACPP_API_VERSION_CURRENT 10 -#define FLACPP_API_VERSION_REVISION 0 -#define FLACPP_API_VERSION_AGE 0 +#define FLACPP_API_VERSION_REVISION 0 /**< see above */ +#define FLACPP_API_VERSION_AGE 0 /**< see above */ /* \} */ diff --git a/include/FLAC/callback.h b/include/FLAC/callback.h index 59d2ee0c..435e72f0 100644 --- a/include/FLAC/callback.h +++ b/include/FLAC/callback.h @@ -168,12 +168,12 @@ typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle); * a data source is not seekable by setting the \a seek field to \c NULL. */ typedef struct { - FLAC__IOCallback_Read read; - FLAC__IOCallback_Write write; - FLAC__IOCallback_Seek seek; - FLAC__IOCallback_Tell tell; - FLAC__IOCallback_Eof eof; - FLAC__IOCallback_Close close; + FLAC__IOCallback_Read read; ///< See FLAC__IOCallbacks + FLAC__IOCallback_Write write; ///< See FLAC__IOCallbacks + FLAC__IOCallback_Seek seek; ///< See FLAC__IOCallbacks + FLAC__IOCallback_Tell tell; ///< See FLAC__IOCallbacks + FLAC__IOCallback_Eof eof; ///< See FLAC__IOCallbacks + FLAC__IOCallback_Close close; ///< See FLAC__IOCallbacks } FLAC__IOCallbacks; /* \} */ diff --git a/include/FLAC/export.h b/include/FLAC/export.h index cde72b73..983f13b1 100644 --- a/include/FLAC/export.h +++ b/include/FLAC/export.h @@ -49,13 +49,24 @@ * This module contains \#defines and symbols for exporting function * calls, and providing version information and compiled-in features. * - * If you are compiling with MSVC and will link to the static library - * (libFLAC.lib) you should define FLAC__NO_DLL in your project to - * make sure the symbols are exported properly. + * If you are compiling for Windows (with Visual Studio or MinGW for + * example) and will link to the static library (libFLAC++.lib) you + * should define FLAC__NO_DLL in your project to make sure the symbols + * are exported properly. * * \{ */ +/** This \#define is used internally in libFLAC and its headers to make + * sure the correct symbols are exported when working with shared + * libraries. On Windows, this \#define is set to __declspec(dllexport) + * when compiling libFLAC into a library and to __declspec(dllimport) + * when the headers are used to link to that DLL. On non-Windows systems + * it is used to set symbol visibility. + * + * Because of this, the define FLAC__NO_DLL must be defined when linking + * to libFLAC statically or linking will fail. + */ /* This has grown quite complicated. FLAC__NO_DLL is used by MSVC sln * files and CMake, which build either static or shared. autotools can * build static, shared or **both**. Therefore, DLL_EXPORT, which is set -- cgit v1.2.1