*: doxygen fixups

doc/doxygen.conf.in

@@ -1104,7 +1104,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = GCC_CHECK_VERSION(major,minor)=0 CLANG_OR_GCC_VERSION(major,minor)=0 GCC_OLDER_THAN(major,minor)=0
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.

src/AudioFormat.hxx

@@ -99,8 +99,8 @@ struct AudioFormat {
 	}
 
 	/**
-	 * Clears the #audio_format object, i.e. sets all attributes to an
-	 * undefined (invalid) value.
+	 * Clears the object, i.e. sets all attributes to an undefined
+	 * (invalid) value.
 	 */
 	void Clear() {
 		sample_rate = 0;
@@ -185,8 +185,6 @@ audio_valid_sample_rate(unsigned sample_rate)
 
 /**
  * Checks whether the sample format is valid.
- *
- * @param bits the number of significant bits per sample
  */
 static inline bool
 audio_valid_sample_format(SampleFormat format)
@@ -289,10 +287,10 @@ AudioFormat::GetTimeToSize() const
 }
 
 /**
- * Renders a #sample_format enum into a string, e.g. for printing it
+ * Renders a #SampleFormat enum into a string, e.g. for printing it
  * in a log file.
  *
- * @param format a #sample_format enum value
+ * @param format a #SampleFormat enum value
  * @return the string
  */
 gcc_pure gcc_malloc
@@ -300,12 +298,12 @@ const char *
 sample_format_to_string(SampleFormat format);
 
 /**
- * Renders the #audio_format object into a string, e.g. for printing
+ * Renders the #AudioFormat object into a string, e.g. for printing
  * it in a log file.
  *
- * @param af the #audio_format object
+ * @param af the #AudioFormat object
  * @param s a buffer to print into
- * @return the string, or nullptr if the #audio_format object is invalid
+ * @return the string, or nullptr if the #AudioFormat object is invalid
  */
 gcc_pure gcc_malloc
 const char *

src/AudioParser.hxx

@@ -30,12 +30,12 @@ class Error;
 
 /**
  * Parses a string in the form "SAMPLE_RATE:BITS:CHANNELS" into an
- * #audio_format.
+ * #AudioFormat.
  *
  * @param dest the destination #audio_format struct
  * @param src the input string
  * @param mask if true, then "*" is allowed for any number of items
- * @param error_r location to store the error occurring, or NULL to
+ * @param error location to store the error occurring, or NULL to
  * ignore errors
  * @return true on success
  */

src/MusicChunk.hxx

@@ -119,13 +119,10 @@ struct MusicChunk {
 	 * where you may write into.  After you are finished, call
 	 * Expand().
 	 *
-	 * @param chunk the MusicChunk object
-	 * @param audio_format the audio format for the appended data;
+	 * @param af the audio format for the appended data;
 	 * must stay the same for the life cycle of this chunk
 	 * @param data_time the time within the song
 	 * @param bit_rate the current bit rate of the source file
-	 * @param max_length_r the maximum write length is returned
-	 * here
 	 * @return a writable buffer, or nullptr if the chunk is full
 	 */
 	WritableBuffer<void> Write(AudioFormat af,
@@ -136,8 +133,7 @@ struct MusicChunk {
 	 * Increases the length of the chunk after the caller has written to
 	 * the buffer returned by Write().
 	 *
-	 * @param chunk the MusicChunk object
-	 * @param audio_format the audio format for the appended data; must
+	 * @param af the audio format for the appended data; must
 	 * stay the same for the life cycle of this chunk
 	 * @param length the number of bytes which were appended
 	 * @return true if the chunk is full

src/db/DatabaseGlue.hxx

@@ -31,7 +31,7 @@ class Error;
 /**
  * Initialize the database library.
  *
- * @param param the database configuration block
+ * @param block the database configuration block
  */
 Database *
 DatabaseGlobalInit(EventLoop &loop, DatabaseListener &listener,

src/db/update/InotifySource.hxx

@@ -46,7 +46,8 @@ public:
 	 * Creates a new inotify source and registers it in the
 	 * #EventLoop.
 	 *
-	 * @param a callback invoked for events received from the kernel
+	 * @param callback a callback invoked for events received from
+	 * the kernel
 	 */
 	static InotifySource *Create(EventLoop &_loop,
 				     mpd_inotify_callback_t callback,

src/decoder/DecoderAPI.hxx

@@ -197,7 +197,6 @@ decoder_data(Decoder &decoder, InputStream &is,
  * This function is called by the decoder plugin when it has
  * successfully decoded a tag.
  *
- * @param decoder the decoder object
  * @param is an input stream which is buffering while we are waiting
  * for the player
  * @param tag the tag to send
@@ -216,9 +215,8 @@ decoder_tag(Decoder &decoder, InputStream &is, Tag &&tag)
 /**
  * Set replay gain values for the following chunks.
  *
- * @param decoder the decoder object
- * @param rgi the replay_gain_info object; may be nullptr to invalidate
- * the previous replay gain values
+ * @param replay_gain_info the replay_gain_info object; may be nullptr
+ * to invalidate the previous replay gain values
  */
 void
 decoder_replay_gain(Decoder &decoder,
@@ -226,10 +224,6 @@ decoder_replay_gain(Decoder &decoder,
 
 /**
  * Store MixRamp tags.
- *
- * @param decoder the decoder object
- * @param mixramp_start the mixramp_start tag; may be nullptr to invalidate
- * @param mixramp_end the mixramp_end tag; may be nullptr to invalidate
  */
 void
 decoder_mixramp(Decoder &decoder, MixRampInfo &&mix_ramp);

src/decoder/DecoderPlugin.hxx

@@ -107,8 +107,7 @@ struct DecoderPlugin {
 	/**
 	 * Initialize a decoder plugin.
 	 *
-	 * @param param a configuration block for this plugin, or nullptr if none
-	 * is configured
+	 * @param block a configuration block for this plugin
 	 * @return true if the plugin was initialized successfully, false if
 	 * the plugin is not available
 	 */

src/encoder/EncoderInterface.hxx

@@ -144,7 +144,6 @@ encoder_flush(Encoder *encoder, Error &error)
  * a new one.
  *
  * @param encoder the encoder
- * @param tag the tag object
  * @return true on success
  */
 static inline bool
@@ -243,7 +242,6 @@ encoder_read(Encoder *encoder, void *dest, size_t length)
 /**
  * Get mime type of encoded content.
  *
- * @param plugin the encoder plugin
  * @return an constant string, nullptr on failure
  */
 static inline const char *

src/encoder/EncoderPlugin.hxx

@@ -64,15 +64,14 @@ struct EncoderPlugin {
  * Creates a new encoder object.
  *
  * @param plugin the encoder plugin
- * @param param optional configuration
  * @param error location to store the error occurring, or nullptr to ignore errors.
  * @return an encoder object on success, nullptr on failure
  */
 static inline Encoder *
 encoder_init(const EncoderPlugin &plugin, const ConfigBlock &block,
-	     Error &error_r)
+	     Error &error)
 {
-	return plugin.init(block, error_r);
+	return plugin.init(block, error);
 }
 
 #endif

src/event/ServerSocket.hxx

@@ -72,8 +72,7 @@ public:
 	 * Add a listener on a port on all interfaces.
 	 *
 	 * @param port the TCP port
-	 * @param error_r location to store the error occurring, or nullptr to
-	 * ignore errors
+	 * @param error location to store the error occurring
 	 * @return true on success
 	 */
 	bool AddPort(unsigned port, Error &error);
@@ -84,8 +83,7 @@ public:
 	 *
 	 * @param hostname the host name to be resolved
 	 * @param port the TCP port
-	 * @param error_r location to store the error occurring, or nullptr to
-	 * ignore errors
+	 * @param error location to store the error occurring
 	 * @return true on success
 	 */
 	bool AddHost(const char *hostname, unsigned port, Error &error);
@@ -94,8 +92,7 @@ public:
 	 * Add a listener on a Unix domain socket.
 	 *
 	 * @param path the absolute socket path
-	 * @param error_r location to store the error occurring, or nullptr to
-	 * ignore errors
+	 * @param error location to store the error occurring
 	 * @return true on success
 	 */
 	bool AddPath(AllocatedPath &&path, Error &error);

src/filter/FilterConfig.hxx

@@ -34,7 +34,7 @@ class Error;
  * configured filter sections.
  * @param chain the chain to append filters on
  * @param spec the filter chain specification
- * @param error_r space to return an error description
+ * @param error space to return an error description
  * @return true on success
  */
 bool

src/filter/FilterInternal.hxx

@@ -38,12 +38,10 @@ public:
 	/**
 	 * Opens the filter, preparing it for FilterPCM().
 	 *
-	 * @param filter the filter object
 	 * @param af the audio format of incoming data; the
 	 * plugin may modify the object to enforce another input
 	 * format
-	 * @param error location to store the error occurring, or nullptr
-	 * to ignore errors.
+	 * @param error location to store the error occurring
 	 * @return the format of outgoing data or
 	 * AudioFormat::Undefined() on error
 	 */
@@ -57,10 +55,8 @@ public:
 	/**
 	 * Filters a block of PCM data.
 	 *
-	 * @param filter the filter object
 	 * @param src the input buffer
-	 * @param error location to store the error occurring, or nullptr
-	 * to ignore errors.
+	 * @param error location to store the error occurring
 	 * @return the destination buffer on success (will be
 	 * invalidated by Close() or FilterPCM()), nullptr on
 	 * error

src/filter/FilterPlugin.hxx

@@ -43,7 +43,7 @@ struct filter_plugin {
  * Creates a new instance of the specified filter plugin.
  *
  * @param plugin the filter plugin
- * @param param optional configuration section
+ * @param block configuration section
  * @param error location to store the error occurring, or nullptr to
  * ignore errors.
  * @return a new filter object, or nullptr on error
@@ -56,7 +56,7 @@ filter_new(const struct filter_plugin *plugin,
  * Creates a new filter, loads configuration and the plugin name from
  * the specified configuration section.
  *
- * @param param the configuration section
+ * @param block the configuration section
  * @param error location to store the error occurring, or nullptr to
  * ignore errors.
  * @return a new filter object, or nullptr on error

src/filter/plugins/ReplayGainFilterPlugin.hxx

@@ -38,9 +38,9 @@ replay_gain_filter_set_mixer(Filter *_filter, Mixer *mixer,
 			     unsigned base);
 
 /**
- * Sets a new #replay_gain_info at the beginning of a new song.
+ * Sets a new #ReplayGainInfo at the beginning of a new song.
  *
- * @param info the new #replay_gain_info value, or nullptr if no replay
+ * @param info the new #ReplayGainInfo value, or nullptr if no replay
  * gain data is available for the current song
  */
 void

src/fs/io/TextFile.hxx

@@ -59,7 +59,6 @@ public:
 	 * Use Check() after nullptr has been returned to check
 	 * whether an error occurred or end-of-file has been reached.
 	 *
-	 * @param file the source file, opened in text mode
 	 * @return a pointer to the line, or nullptr on end-of-file or error
 	 */
 	char *ReadLine();

src/input/InputStream.hxx

@@ -350,7 +350,6 @@ public:
 	 *
 	 * The caller must lock the mutex.
 	 *
-	 * @param is the InputStream object
 	 * @param ptr the buffer to read into
 	 * @param size the maximum number of bytes to read
 	 * @return the number of bytes read

src/lib/upnp/WorkQueue.hxx

@@ -66,10 +66,7 @@ class WorkQueue {
 
 public:
 	/** Create a WorkQueue
-	 * @param name for message printing
-	 * @param hi number of tasks on queue before clients blocks. Default 0
-	 *    meaning no limit. hi == -1 means that the queue is disabled.
-	 * @param lo minimum count of tasks before worker starts. Default 1.
+	 * @param _name for message printing
 	 */
 	WorkQueue(const char *_name)
 		:name(_name),
@@ -86,7 +83,7 @@ public:
 	/** Start the worker threads.
 	 *
 	 * @param nworkers number of threads copies to start.
-	 * @param start_routine thread function. It should loop
+	 * @param workproc thread function. It should loop
 	 *      taking (QueueWorker::take()) and executing tasks.
 	 * @param arg initial parameter to thread function.
 	 * @return true if ok.

src/mixer/MixerControl.hxx

@@ -19,7 +19,7 @@
 
 /** \file
  *
- * Functions which manipulate a #mixer object.
+ * Functions which manipulate a #Mixer object.
  */
 
 #ifndef MPD_MIXER_CONTROL_HXX

src/net/Resolver.hxx

@@ -36,9 +36,6 @@ extern const Domain resolver_domain;
 /**
  * Converts the specified socket address into a string in the form
  * "IP:PORT".
- *
- * @param sa the sockaddr struct
- * @param length the length of #sa in bytes
  */
 gcc_pure
 std::string

src/net/SocketUtil.hxx

@@ -37,7 +37,6 @@ class Error;
  * @param type the socket type, e.g. SOCK_STREAM
  * @param protocol the protocol, usually 0 to let the kernel choose
  * @param address the address to listen on
- * @param address_length the size of #address
  * @param backlog the backlog parameter for the listen() system call
  * @param error location to store the error occurring, or NULL to
  * ignore errors

src/output/MultipleOutputs.hxx

@@ -120,7 +120,7 @@ public:
 	 * Opens all audio outputs which are not disabled.
 	 *
 	 * @param audio_format the preferred audio format
-	 * @param buffer the #music_buffer where consumed #MusicChunk objects
+	 * @param _buffer the #music_buffer where consumed #MusicChunk objects
 	 * should be returned
 	 * @return true on success, false on failure
 	 */

src/output/plugins/httpd/HttpdClient.hxx

@@ -124,7 +124,7 @@ class HttpdClient final : BufferedSocket {
 public:
 	/**
 	 * @param httpd the HTTP output device
-	 * @param fd the socket file descriptor
+	 * @param _fd the socket file descriptor
 	 */
 	HttpdClient(HttpdOutput &httpd, int _fd, EventLoop &_loop,
 		    bool _metadata_supported);

src/pcm/PcmConvert.hxx

@@ -74,11 +74,8 @@ public:
 	/**
 	 * Converts PCM data between two audio formats.
 	 *
-	 * @param src_format the source audio format
 	 * @param src the source PCM buffer
-	 * @param dest_format the requested destination audio format
-	 * @param error_r location to store the error occurring, or nullptr to
-	 * ignore errors
+	 * @param error location to store the error occurring
 	 * @return the destination buffer, or nullptr on error
 	 */
 	ConstBuffer<void> Convert(ConstBuffer<void> src, Error &error);

src/pcm/PcmDither.hxx

@@ -36,9 +36,9 @@ public:
 	 * Shift the given sample by #SBITS-#DBITS to the right, and
 	 * apply dithering.
 	 *
-	 * @param ST the input sample type
-	 * @param SBITS the input bit width
-	 * @param DBITS the output bit width
+	 * @tparam ST the input sample type
+	 * @tparam SBITS the input bit width
+	 * @tparam DBITS the output bit width
 	 * @param sample the input sample value
 	 */
 	template<typename ST, unsigned SBITS, unsigned DBITS>

src/pcm/PcmExport.hxx

@@ -86,7 +86,7 @@ struct PcmExport {
 	uint8_t reverse_endian;
 
 	/**
-	 * Open the #pcm_export_state object.
+	 * Open the object.
 	 *
 	 * There is no "close" method.  This function may be called multiple
 	 * times to reuse the object.

src/pcm/PcmFormat.hxx

@@ -33,9 +33,8 @@ class PcmDither;
  * Converts PCM samples to 16 bit.  If the source format is 24 bit,
  * then dithering is applied.
  *
- * @param buffer a PcmBuffer object
- * @param dither a pcm_dither object for 24-to-16 conversion
- * @param bits the number of in the source buffer
+ * @param buffer a #PcmBuffer object
+ * @param dither a #PcmDither object for 24-to-16 conversion
  * @param src the source PCM buffer
  * @return the destination buffer
  */
@@ -47,8 +46,7 @@ pcm_convert_to_16(PcmBuffer &buffer, PcmDither &dither,
 /**
  * Converts PCM samples to 24 bit (32 bit alignment).
  *
- * @param buffer a PcmBuffer object
- * @param bits the number of in the source buffer
+ * @param buffer a #PcmBuffer object
  * @param src the source PCM buffer
  * @return the destination buffer
  */
@@ -60,8 +58,7 @@ pcm_convert_to_24(PcmBuffer &buffer,
 /**
  * Converts PCM samples to 32 bit.
  *
- * @param buffer a PcmBuffer object
- * @param bits the number of in the source buffer
+ * @param buffer a #PcmBuffer object
  * @param src the source PCM buffer
  * @return the destination buffer
  */
@@ -73,11 +70,8 @@ pcm_convert_to_32(PcmBuffer &buffer,
 /**
  * Converts PCM samples to 32 bit floating point.
  *
- * @param buffer a PcmBuffer object
- * @param bits the number of in the source buffer
+ * @param buffer a #PcmBuffer object
  * @param src the source PCM buffer
- * @param src_size the size of #src in bytes
- * @param dest_size_r returns the number of bytes of the destination buffer
  * @return the destination buffer
  */
 gcc_pure

src/pcm/PcmPack.hxx

@@ -35,7 +35,6 @@
  *
  * @param dest the destination buffer (array of triples)
  * @param src the source buffer
- * @param num_samples the number of samples to convert
  */
 void
 pcm_pack_24(uint8_t *dest, const int32_t *src, const int32_t *src_end);
@@ -46,7 +45,6 @@ pcm_pack_24(uint8_t *dest, const int32_t *src, const int32_t *src_end);
  *
  * @param dest the destination buffer
  * @param src the source buffer (array of triples)
- * @param num_samples the number of samples to convert
  */
 void
 pcm_unpack_24(int32_t *dest, const uint8_t *src, const uint8_t *src_end);

src/pcm/Resampler.hxx

@@ -58,10 +58,7 @@ public:
 	 * Resamples a block of PCM data.
 	 *
 	 * @param src the input buffer
-	 * @param src_size the size of #src_buffer in bytes
-	 * @param dest_size_r the size of the returned buffer
-	 * @param error location to store the error occurring, or nullptr
-	 * to ignore errors.
+	 * @param error location to store the error occurring
 	 * @return the destination buffer on success (will be
 	 * invalidated by filter_close() or filter_filter()), nullptr on
 	 * error

src/playlist/PlaylistPlugin.hxx

@@ -33,7 +33,7 @@ struct playlist_plugin {
 	/**
 	 * Initialize the plugin.  Optional method.
 	 *
-	 * @param param a configuration block for this plugin, or nullptr
+	 * @param block a configuration block for this plugin, or nullptr
 	 * if none is configured
 	 * @return true if the plugin was initialized successfully,
 	 * false if the plugin is not available
@@ -68,7 +68,7 @@ struct playlist_plugin {
 /**
  * Initialize a plugin.
  *
- * @param param a configuration block for this plugin, or nullptr if none
+ * @param block a configuration block for this plugin, or nullptr if none
  * is configured
  * @return true if the plugin was initialized successfully, false if
  * the plugin is not available

src/playlist/PlaylistStream.hxx

@@ -31,8 +31,6 @@ class Path;
  * Opens a playlist from a local file.
  *
  * @param path the path of the playlist file
- * @param is_r on success, an #InputStream object is returned here,
- * which must be closed after the playlist_provider object is freed
  * @return a playlist, or nullptr on error
  */
 gcc_nonnull_all

src/queue/Playlist.hxx

@@ -295,7 +295,7 @@ public:
 	 * Seek within the current song.  Fails if MPD is not currently
 	 * playing.
 	 *
-	 * @param time the time in seconds
+	 * @param seek_time the time
 	 * @param relative if true, then the specified time is relative to the
 	 * current position
 	 */

src/queue/Queue.hxx

@@ -340,8 +340,6 @@ struct Queue {
 	/**
 	 * Shuffles a (position) range in the queue.  The songs are physically
 	 * shuffled, not by using the "order" mapping.
-	 *
-	 * @param reorder false to suppress updating the order list
 	 */
 	void ShuffleRange(unsigned start, unsigned end);
 

src/tag/TagBuilder.hxx

@@ -138,7 +138,7 @@ public:
 	 *
 	 * @param type the type of the new tag item
 	 * @param value the value of the tag item (not null-terminated)
-	 * @param len the length of #value
+	 * @param length the length of #value
 	 */
 	gcc_nonnull_all
 	void AddItem(TagType type, const char *value, size_t length);

src/tag/TagRva2.hxx

@@ -26,7 +26,7 @@ struct id3_tag;
 struct ReplayGainInfo;
 
 /**
- * Parse the RVA2 tag, and fill the #replay_gain_info struct.  This is
+ * Parse the RVA2 tag, and fill the #ReplayGainInfo struct.  This is
  * used by decoder plugins with ID3 support.
  *
  * @return true on success

src/util/Tokenizer.hxx

@@ -71,7 +71,7 @@ public:
 	/**
 	 * Reads the next unquoted word from the input string.
 	 *
-	 * @param error_r if this function returns nullptr and **input_p!=0, it
+	 * @param error if this function returns nullptr and **input_p!=0, it
 	 * provides an #Error object in this argument
 	 * @return a pointer to the null-terminated word, or nullptr
 	 * on error or end of line
@@ -83,9 +83,7 @@ public:
 	 * escapes the following character.  This function modifies the input
 	 * string.
 	 *
-	 * @param input_p the input string; this function returns a pointer to
-	 * the first non-whitespace character of the following token
-	 * @param error_r if this function returns nullptr and **input_p!=0, it
+	 * @param error if this function returns nullptr and **input_p!=0, it
 	 * provides an #Error object in this argument
 	 * @return a pointer to the null-terminated string, or nullptr on error
 	 * or end of line
@@ -97,7 +95,7 @@ public:
 	 * input.  This is a wrapper for NextUnquoted() and
 	 * NextString().
 	 *
-	 * @param error_r if this function returns nullptr and
+	 * @param error if this function returns nullptr and
 	 * **input_p!=0, it provides an #Error object in
 	 * this argument
 	 * @return a pointer to the null-terminated string, or nullptr

src/util/VarSize.hxx

@@ -42,7 +42,7 @@
  * example when you want to store a variable-length string as the last
  * attribute without the overhead of a second allocation.
  *
- * @param T a struct/class with a variable-size last attribute
+ * @tparam T a struct/class with a variable-size last attribute
  * @param declared_tail_size the declared size of the last element in
  * #T
  * @param real_tail_size the real required size of the last element in