[PATCH v2] ALSA: compress: document 'chan_map' member in snd_dec_opus

[PATCH v2] ALSA: compress: document 'chan_map' member in snd_dec_opus

[Kriish Sharma]

When building kernel docs, the following warning appeared:

  WARNING: ./include/uapi/sound/compress_params.h:364
  struct member 'chan_map' not described in 'snd_dec_opus'

The inline struct 'snd_dec_opus_ch_map' inside 'snd_dec_opus' was not
properly documented. This patch documents the 'chan_map' member and its
fields (stream_count, coupled_count, channel_map), resolving the warning.

Fixes: 5d36370f3431 ("ALSA: compress: add raw opus codec define and opus decoder structs")
Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>

v2:
  - Use proper subject prefix ("ALSA: compress: ...")
  - Add Fixes tag for the commit that introduced snd_dec_opus
  - Add Suggested-by tag (Bagas Sanjaya)

---
 include/uapi/sound/compress_params.h | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/include/uapi/sound/compress_params.h b/include/uapi/sound/compress_params.h
index faf4fa911f7f..d7db6b4e1166 100644
--- a/include/uapi/sound/compress_params.h
+++ b/include/uapi/sound/compress_params.h
@@ -336,16 +336,14 @@ struct snd_dec_ape {
  * @mapping_family: Order and meaning of output channels. Only values 0 and 1
  * are expected; values 2..255 are not recommended for playback.
  *
- * Optional channel mapping table. Describes mapping of opus streams to decoded
- * channels.
- * @struct snd_dec_opus_ch_map
- *	@stream_count: Number of streams encoded in each Ogg packet.
- *	@coupled_count: Number of streams whose decoders are used for two
- *		channels.
- *	@channel_map: describes which decoded channel to be used for each one.
- *		See RFC doc for details.
- *		This supports only mapping families 0 and 1, therefore max
- *		number of channels is 8.
+ * @chan_map: Optional channel mapping table. Describes mapping of opus streams
+ *            to decoded channels. Fields:
+ * @chan_map.stream_count: Number of streams encoded in each Ogg packet.
+ * @chan_map.coupled_count: Number of streams whose decoders are used
+ *                          for two channels.
+ * @chan_map.channel_map: Which decoded channel to be used for each one.
+ *                        Supports only mapping families 0 and 1,
+ *                        max number of channels is 8.
  *
  * These options were extracted from RFC7845 Section 5.
  */
-- 
2.34.1

Re: [PATCH v2] ALSA: compress: document 'chan_map' member in snd_dec_opus

[Takashi Iwai]

On Sat, 27 Sep 2025 16:27:08 +0200,
Kriish Sharma wrote:
> 
> When building kernel docs, the following warning appeared:
> 
>   WARNING: ./include/uapi/sound/compress_params.h:364
>   struct member 'chan_map' not described in 'snd_dec_opus'
> 
> The inline struct 'snd_dec_opus_ch_map' inside 'snd_dec_opus' was not
> properly documented. This patch documents the 'chan_map' member and its
> fields (stream_count, coupled_count, channel_map), resolving the warning.
> 
> Fixes: 5d36370f3431 ("ALSA: compress: add raw opus codec define and opus decoder structs")
> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>
> 
> v2:
>   - Use proper subject prefix ("ALSA: compress: ...")
>   - Add Fixes tag for the commit that introduced snd_dec_opus
>   - Add Suggested-by tag (Bagas Sanjaya)

Thanks, applied now.


Takashi