update docs

spa/include/spa/param/audio/raw.h

@@ -62,47 +62,27 @@ extern "C" {
 #define SPA_TYPE_AUDIO_FORMAT__F64LE		SPA_TYPE_AUDIO_FORMAT_BASE "F64LE"
 #define SPA_TYPE_AUDIO_FORMAT__F64BE		SPA_TYPE_AUDIO_FORMAT_BASE "F64BE"
 
-/**
+/** Extra audio flags */
- * spa_audio_flags:
- * @SPA_AUDIO_FLAG_NONE: no valid flag
- * @SPA_AUDIO_FLAG_UNPOSITIONED: the position array explicitly
- *     contains unpositioned channels.
- *
- * Extra audio flags
- */
 enum spa_audio_flags {
-	SPA_AUDIO_FLAG_NONE = 0,
+	SPA_AUDIO_FLAG_NONE		= 0,		/*< no valid flag */
-	SPA_AUDIO_FLAG_UNPOSITIONED = (1 << 0)
+	SPA_AUDIO_FLAG_UNPOSITIONED	= (1 << 0),	/*< the position array explicitly
+							 *  contains unpositioned channels. */
 };
 
-/**
+/** Layout of the audio samples for the different channels.  */
- * spa_audio_layout:
- * @SPA_AUDIO_LAYOUT_INTERLEAVED: interleaved audio
- * @SPA_AUDIO_LAYOUT_NON_INTERLEAVED: non-interleaved audio
- *
- * Layout of the audio samples for the different channels.
- */
 enum spa_audio_layout {
-	SPA_AUDIO_LAYOUT_INTERLEAVED = 0,
+	SPA_AUDIO_LAYOUT_INTERLEAVED = 0,	/*< interleaved audio */
-	SPA_AUDIO_LAYOUT_NON_INTERLEAVED
+	SPA_AUDIO_LAYOUT_NON_INTERLEAVED	/*< non-interleaved audio */
 };
 
-/**
+/** Audio information description */
- * spa_audio_info_raw:
- * @format: the format
- * @flags: extra flags
- * @layout: the sample layout
- * @rate: the sample rate
- * @channels: the number of channels
- * @channel_mask: the channel mask
- */
 struct spa_audio_info_raw {
-	uint32_t format;
+	uint32_t format;		/*< format, one of SPA_TYPE__AudioFormat */
-	enum spa_audio_flags flags;
+	enum spa_audio_flags flags;	/*< extra flags */
-	enum spa_audio_layout layout;
+	enum spa_audio_layout layout;	/*< sample layout */
-	uint32_t rate;
+	uint32_t rate;			/*< sample rate */
-	uint32_t channels;
+	uint32_t channels;		/*< number of channels */
-	uint32_t channel_mask;
+	uint32_t channel_mask;		/*< channel mask */
 };
 
 #ifdef __cplusplus

spa/include/spa/param/video/chroma.h

@@ -24,8 +24,7 @@
 extern "C" {
 #endif
 
-/**
+/** Various Chroma sitings.
- * spa_video_chroma_site:
  * @SPA_VIDEO_CHROMA_SITE_UNKNOWN: unknown cositing
  * @SPA_VIDEO_CHROMA_SITE_NONE: no cositing
  * @SPA_VIDEO_CHROMA_SITE_H_COSITED: chroma is horizontally cosited
@@ -35,8 +34,6 @@ extern "C" {
  * @SPA_VIDEO_CHROMA_SITE_JPEG: jpeg style cositing, also for mpeg1 and mjpeg
  * @SPA_VIDEO_CHROMA_SITE_MPEG2: mpeg2 style cositing
  * @SPA_VIDEO_CHROMA_SITE_DV: DV style cositing
- *
- * Various Chroma sitings.
  */
 enum spa_video_chroma_site {
 	SPA_VIDEO_CHROMA_SITE_UNKNOWN = 0,

spa/include/spa/support/log.h

@@ -41,40 +41,33 @@ enum spa_log_level {
 };
 
 /**
- * struct spa_log:
- *
  * The Log interface
  */
 struct spa_log {
-	/* the version of this log. This can be used to expand this
+	/** the version of this log. This can be used to expand this
 	 * structure in the future */
 #define SPA_VERSION_LOG	0
 	uint32_t version;
 	/**
-	 * struct spa_log::info
-	 *
 	 * Extra information about the log
 	 */
 	const struct spa_dict *info;
 
 	/**
-	 * struct spa_log::level
-	 *
 	 * Logging level, everything above this level is not logged
 	 */
 	enum spa_log_level level;
 
 	/**
-	 * struct spa_log::log
-	 * @log: a #struct spa_log
-	 * @level: a #enum spa_log_level
-	 * @file: the file name
-	 * @line: the line number
-	 * @func: the function name
-	 * @fmt: printf style format
-	 * @...: format arguments
-	 *
 	 * Log a message with the given log level.
+	 *
+	 * \param log a spa_log
+	 * \param level a spa_log_level
+	 * \param file the file name
+	 * \param line the line number
+	 * \param func the function name
+	 * \param fmt printf style format
+	 * \param ... format arguments
 	 */
 	void (*log) (struct spa_log *log,
 		     enum spa_log_level level,
@@ -84,16 +77,15 @@ struct spa_log {
 		     const char *fmt, ...) SPA_PRINTF_FUNC(6, 7);
 
 	/**
-	 * struct spa_log::logv
-	 * @log: a #struct spa_log
-	 * @level: a #enum spa_log_level
-	 * @file: the file name
-	 * @line: the line number
-	 * @func: the function name
-	 * @fmt: printf style format
-	 * @args: format arguments
-	 *
 	 * Log a message with the given log level.
+	 *
+	 * \param log a spa_log
+	 * \param level a spa_log_level
+	 * \param file the file name
+	 * \param line the line number
+	 * \param func the function name
+	 * \param fmt printf style format
+	 * \param args format arguments
 	 */
 	void (*logv) (struct spa_log *log,
 		      enum spa_log_level level,

spa/include/spa/support/loop.h

@@ -67,8 +67,6 @@ typedef int (*spa_invoke_func_t) (struct spa_loop *loop,
 				  void *user_data);
 
 /**
- * spa_loop:
- *
  * Register sources and work items to an event loop
  */
 struct spa_loop {
@@ -114,8 +112,6 @@ struct spa_loop_control_hooks {
 };
 
 /**
- * spa_loop_control:
- *
  * Control an event loop
  */
 struct spa_loop_control {
@@ -154,8 +150,6 @@ typedef void (*spa_source_timer_func_t) (void *data, uint64_t expirations);
 typedef void (*spa_source_signal_func_t) (void *data, int signal_number);
 
 /**
- * struct spa_loop_utils:
- *
  * Create sources for an event loop
  */
 struct spa_loop_utils {

spa/include/spa/support/plugin.h

@@ -38,26 +38,22 @@ struct spa_handle {
 	/* user_data that can be set by the application */
 	void *user_data;
 	/**
-	 * spa_handle::get_interface:
+	 * Get the interface provided by \a handle with \a interface_id.
-	 * @handle: a #spa_handle
-	 * @interface_id: the interface id
-	 * @interface: result to hold the interface.
 	 *
-	 * Get the interface provided by @handle with @interface_id.
+	 * \param handle a spa_handle
-	 *
+	 * \param interface_id the interface id
-	 * Returns: #SPA_RESULT_OK on success
+	 * \param interface result to hold the interface.
-	 *          #SPA_RESULT_NOT_IMPLEMENTED when there are no extensions
+	 * \return 0 on success
-	 *          #SPA_RESULT_INVALID_ARGUMENTS when handle or info is %NULL
+	 *         -ENOTSUP when there are no interfaces
+	 *         -EINVAL when handle or info is NULL
 	 */
 	int (*get_interface) (struct spa_handle *handle, uint32_t interface_id, void **interface);
 	/**
-	 * spa_handle::clear
+	 * Clean up the memory of \a handle. After this, \a handle should not be used
-	 * @handle: a pointer to memory
-	 *
-	 * Clean up the memory of @handle. After this, @handle should not be used
 	 * anymore.
 	 *
-	 * Returns: #SPA_RESULT_OK on success
+	 * \param handle a pointer to memory
+	 * \return 0 on success
 	 */
 	int (*clear) (struct spa_handle *handle);
 };
@@ -66,29 +62,24 @@ struct spa_handle {
 #define spa_handle_clear(h)		(h)->clear((h))
 
 /**
- * struct spa_interface_info:
- * @type: the type of the interface, can be used to get the interface
- *
  * This structure lists the information about available interfaces on
  * handles.
  */
 struct spa_interface_info {
-	const char *type;
+	const char *type;	/*< the type of the interface, can be
+				 *  used to get the interface */
 };
 
 /**
- * struct spa_support:
- * @type: the type of the support item
- * @data: specific data for the item
- *
  * Extra supporting infrastructure passed to the init() function of
  * a factory. It can be extra information or interfaces such as logging.
  */
 struct spa_support {
-	const char *type;
+	const char *type;	/*< the type of the support item */
-	void *data;
+	void *data;		/*< specific data for the item */
 };
 
+/** Find a support item of the given type */
 static inline void *spa_support_find(const struct spa_support *support,
 				     uint32_t n_support,
 				     const char *type)
@@ -107,42 +98,33 @@ struct spa_handle_factory {
 #define SPA_VERSION_HANDLE_FACTORY	0
 	uint32_t version;
 	/**
-	 * spa_handle_factory::name
-	 *
 	 * The name
 	 */
 	const char *name;
 	/**
-	 * spa_handle_factory::info
-	 *
 	 * Extra information about the handles of this factory.
 	 */
 	const struct spa_dict *info;
 	/**
-	 * spa_handle_factory::size
-	 *
 	 * The size of handles from this factory
 	 */
 	const size_t size;
 
 	/**
-	 * spa_handle_factory::init
-	 * @factory: a #spa_handle_factory
-	 * @handle: a pointer to memory
-	 * @info: extra handle specific information, usually obtained
-	 *        from a #spa_monitor. This can be used to configure the handle.
-	 * @support: support items
-	 * @n_support: number of elements in @support
-	 *
 	 * Initialize an instance of this factory. The caller should allocate
-	 * memory at least spa_handle_factory::size bytes and pass this as @handle.
+	 * memory at least size bytes and pass this as \a handle.
 	 *
-	 * @support can optionally contain extra interfaces or data ites that the
+	 * \a support can optionally contain extra interfaces or data items that the
 	 * plugin can use such as a logger.
 	 *
-	 * Returns: #SPA_RESULT_OK on success
+	 * \param factory a spa_handle_factory
-	 *          #SPA_RESULT_NOT_IMPLEMENTED when an instance can't be made
+	 * \param handle a pointer to memory
-	 *          #SPA_RESULT_INVALID_ARGUMENTS when factory or handle are %NULL
+	 * \param info extra handle specific information, usually obtained
+	 *        from a spa_monitor. This can be used to configure the handle.
+	 * \param support support items
+	 * \param n_support number of elements in \a support
+	 * \return 0 on success
+	 *	   < 0 errno type error
 	 */
 	int (*init) (const struct spa_handle_factory *factory,
 		     struct spa_handle *handle,
@@ -152,15 +134,15 @@ struct spa_handle_factory {
 
 	/**
 	 * spa_handle_factory::enum_interface_info:
-	 * @factory: a #spa_handle_factory
+	 * \param factory: a #spa_handle_factory
-	 * @info: result to hold spa_interface_info.
+	 * \param info: result to hold spa_interface_info.
-	 * @index: index to keep track of the enumeration, 0 for first item
+	 * \param index: index to keep track of the enumeration, 0 for first item
 	 *
-	 * Enumerate the interface information for @factory.
+	 * Enumerate the interface information for \a factory.
 	 *
-	 * Returns: 1 when an item is available
+	 * \return 1 when an item is available
 	 *	   0 when no more items are available
-	 *	    -errno on error
+	 *	   < 0 errno type error
 	 */
 	int (*enum_interface_info) (const struct spa_handle_factory *factory,
 				    const struct spa_interface_info **info,
@@ -171,15 +153,13 @@ struct spa_handle_factory {
 #define spa_handle_factory_enum_interface_info(h,...)	(h)->enum_interface_info((h),__VA_ARGS__)
 
 /**
- * spa_handle_factory_enum_func_t:
- * @factory: a location to hold the factory result
- * @index: index to keep track of the enumeration
- *
  * The function signature of the entry point in a plugin.
  *
- * Returns: #SPA_RESULT_OK on success
+ * \param factory a location to hold the factory result
- *          #SPA_RESULT_INVALID_ARGUMENTS when factory is %NULL
+ * \param index index to keep track of the enumeration
- *          #SPA_RESULT_ENUM_END when there are no more factories
+ * \return 1 on success
+ *         0 when there are no more factories
+ *         -EINVAL when factory is NULL
  */
 typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory **factory,
 					       uint32_t *index);
@@ -187,15 +167,13 @@ typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory *
 #define SPA_HANDLE_FACTORY_ENUM_FUNC_NAME "spa_handle_factory_enum"
 
 /**
- * spa_handle_factory_enum:
- * @factory: a location to hold the factory result
- * @index: index to keep track of the enumeration
- *
  * The entry point in a plugin.
  *
- * Returns: 1 on success
+ * \param factory a location to hold the factory result
+ * \param index index to keep track of the enumeration
+ * \return 1 on success
  *	   0 when no more items are available
- *	    -errno on error
+ *	   < 0 errno type error
  */
 int spa_handle_factory_enum(const struct spa_handle_factory **factory, uint32_t *index);
 

spa/include/spa/support/type-map.h

@@ -30,18 +30,14 @@ extern "C" {
 #define SPA_TYPE__TypeMap		SPA_TYPE_INTERFACE_BASE "TypeMap"
 
 /**
- * spa_type_map:
- *
  * Maps between string types and their type id
  */
 struct spa_type_map {
-	/* the version of this structure. This can be used to expand this
+	/** the version of this structure. This can be used to expand this
 	 * structure in the future */
 #define SPA_VERSION_TYPE_MAP	0
 	uint32_t version;
 	/**
-	 * spa_type_map::info
-	 *
 	 * Extra information about the type map
 	 */
 	const struct spa_dict *info;

spa/include/spa/utils/ringbuffer.h

@@ -33,27 +33,23 @@ struct spa_ringbuffer;
 #include <spa/utils/defs.h>
 
 /**
- * spa_ringbuffer:
+ * A ringbuffer type.
- * @readindex: the current read index
- * @writeindex: the current write index
- * @size: the size of the ringbuffer
- * @mask: mask as @size - 1
  */
 struct spa_ringbuffer {
-	uint32_t readindex;
+	uint32_t readindex;	/*< the current read index */
-	uint32_t writeindex;
+	uint32_t writeindex;	/*< the current write index */
-	uint32_t size;
+	uint32_t size;		/*< the size of the ringbuffer */
-	uint32_t mask;
+	uint32_t mask;		/*< mask as \a size - 1, only valid if \a size is
+				 *  a power of 2. */
 };
 
 #define SPA_RINGBUFFER_INIT(size)	(struct spa_ringbuffer) { 0, 0, (size), (size)-1 }
 
 /**
- * spa_ringbuffer_init:
+ * Initialize a spa_ringbuffer with \a size.
- * @rbuf: a #struct spa_ringbuffer
- * @size: the number of elements in the ringbuffer
  *
- * Initialize a #struct spa_ringbuffer with @size.
+ * \param rbuf a spa_ringbuffer
+ * \param size the number of elements in the ringbuffer
  */
 static inline void spa_ringbuffer_init(struct spa_ringbuffer *rbuf, uint32_t size)
 {
@@ -61,10 +57,9 @@ static inline void spa_ringbuffer_init(struct spa_ringbuffer *rbuf, uint32_t siz
 }
 
 /**
- * spa_ringbuffer_clear:
+ * Clear \a rbuf, sets the pointers so that the ringbuffer is empty.
- * @rbuf: a #struct spa_ringbuffer
  *
- * Clear @rbuf
+ * \param rbuf a spa_ringbuffer
  */
 static inline void spa_ringbuffer_clear(struct spa_ringbuffer *rbuf)
 {
@@ -73,53 +68,46 @@ static inline void spa_ringbuffer_clear(struct spa_ringbuffer *rbuf)
 }
 
 /**
- * spa_ringbuffer_get_read_index:
+ * Get the read index and available bytes for reading.
- * @rbuf: a #struct spa_ringbuffer
- * @index: the value of readindex, should be masked to get the
- *         offset in the ringbuffer memory
  *
- * Returns: number of available bytes to read. values < 0 mean
+ * \param rbuf a  spa_ringbuffer
+ * \param index the value of readindex, should be masked to get the
+ *         offset in the ringbuffer memory
+ * \return number of available bytes to read. values < 0 mean
  *         there was an underrun. values > rbuf->size means there
  *         was an overrun.
  */
 static inline int32_t spa_ringbuffer_get_read_index(struct spa_ringbuffer *rbuf, uint32_t *index)
 {
-	int32_t avail;
-
 	*index = __atomic_load_n(&rbuf->readindex, __ATOMIC_RELAXED);
-	avail = (int32_t) (__atomic_load_n(&rbuf->writeindex, __ATOMIC_ACQUIRE) - *index);
+	return (int32_t) (__atomic_load_n(&rbuf->writeindex, __ATOMIC_ACQUIRE) - *index);
-
-	return avail;
 }
 
 /**
- * spa_ringbuffer_read_data:
+ * Read \a len bytes from \a rbuf starting \a offset. \a offset must be masked
- * @rbuf: a #struct spa_ringbuffer
+ * with the size of \a rbuf and len should be smaller than the size.
- * @buffer: memory to read from
- * @offset: offset in @buffer to read from
- * @data: destination memory
- * @len: number of bytes to read
  *
- * Read @len bytes from @rbuf starting @offset. @offset must be masked
+ * \param rbuf a #struct spa_ringbuffer
- * with the size of @rbuf and len should be smaller than the size.
+ * \param buffer memory to read from
+ * \param offset offset in \a buffer to read from
+ * \param data destination memory
+ * \param len number of bytes to read
  */
 static inline void
 spa_ringbuffer_read_data(struct spa_ringbuffer *rbuf,
-			 void *buffer, uint32_t offset, void *data, uint32_t len)
+			 const void *buffer, uint32_t offset, void *data, uint32_t len)
 {
 	uint32_t first = SPA_MIN(len, rbuf->size - offset);
 	memcpy(data, buffer + offset, first);
-	if (SPA_UNLIKELY(len > first)) {
+	if (SPA_UNLIKELY(len > first))
 		memcpy(data + first, buffer, len - first);
 }
-}
 
 /**
- * spa_ringbuffer_read_update:
+ * Update the read pointer to \a index.
- * @rbuf: a #struct spa_ringbuffer
- * @index: new index
  *
- * Update the read pointer to @index
+ * \param rbuf a spa_ringbuffer
+ * \param index new index
  */
 static inline void spa_ringbuffer_read_update(struct spa_ringbuffer *rbuf, int32_t index)
 {
@@ -127,44 +115,47 @@ static inline void spa_ringbuffer_read_update(struct spa_ringbuffer *rbuf, int32
 }
 
 /**
- * spa_ringbuffer_get_write_index:
+ * Get the write index and the number of bytes inside the ringbuffer.
- * @rbuf: a #struct spa_ringbuffer
- * @index: the value of writeindex, should be masked to get the
- *         offset in the ringbuffer memory
  *
- * Returns: the fill level of @rbuf. values < 0 mean
+ * \param rbuf a  spa_ringbuffer
+ * \param index the value of writeindex, should be masked to get the
+ *         offset in the ringbuffer memory
+ * \return the fill level of \a rbuf. values < 0 mean
  *         there was an underrun. values > rbuf->size means there
  *         was an overrun. Subtract from the buffer size to get
  *         the number of bytes available for writing.
  */
 static inline int32_t spa_ringbuffer_get_write_index(struct spa_ringbuffer *rbuf, uint32_t *index)
 {
-	int32_t filled;
-
 	*index = __atomic_load_n(&rbuf->writeindex, __ATOMIC_RELAXED);
-	filled = (int32_t) (*index - __atomic_load_n(&rbuf->readindex, __ATOMIC_ACQUIRE));
+	return (int32_t) (*index - __atomic_load_n(&rbuf->readindex, __ATOMIC_ACQUIRE));
-
-	return filled;
-}
-
-static inline void
-spa_ringbuffer_write_data(struct spa_ringbuffer *rbuf,
-			  void *buffer, uint32_t offset, void *data, uint32_t len)
-{
-	uint32_t first = SPA_MIN(len, rbuf->size - offset);
-	memcpy(buffer + offset, data, first);
-	if (SPA_UNLIKELY(len > first)) {
-		memcpy(buffer, data + first, len - first);
-	}
 }
 
 /**
- * spa_ringbuffer_write_update:
+ * Write \a len bytes to \a rbuf starting \a offset. \a offset must be masked
- * @rbuf: a #struct spa_ringbuffer
+ * with the size of \a rbuf and len should be smaller than the size.
- * @index: new index
  *
- * Update the write pointer to @index
+ * \param rbuf a spa_ringbuffer
+ * \param buffer memory to write to
+ * \param offset offset in \a buffer to write to
+ * \param data source memory
+ * \param len number of bytes to write
+ */
+static inline void
+spa_ringbuffer_write_data(struct spa_ringbuffer *rbuf,
+			  void *buffer, uint32_t offset, const void *data, uint32_t len)
+{
+	uint32_t first = SPA_MIN(len, rbuf->size - offset);
+	memcpy(buffer + offset, data, first);
+	if (SPA_UNLIKELY(len > first))
+		memcpy(buffer, data + first, len - first);
+}
+
+/**
+ * Update the write pointer to \a index
  *
+ * \param rbuf a spa_ringbuffer
+ * \param index new index
  */
 static inline void spa_ringbuffer_write_update(struct spa_ringbuffer *rbuf, int32_t index)
 {

spa/plugins/alsa/alsa-monitor.c

@@ -68,9 +68,6 @@ struct impl {
 	uint32_t index;
 	struct udev_list_entry *devices;
 
-//	uint8_t item_buffer[4096];
-//	struct spa_monitor_item *item;
-
 	snd_ctl_t *ctl_hndl;
 	struct udev_device *dev;
 	char card_name[16];