docs: sound: describe 'chan_map' member in snd_dec_opus

[PATCH] docs: sound: describe 'chan_map' member in snd_dec_opus

Posted by Kriish Sharma 4 months, 1 week ago

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.

Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>
---
 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..e90e2f40732a 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:
+ *              - @stream_count: Number of streams encoded in each Ogg packet.
+ *              - @coupled_count: Number of streams whose decoders are used
+ *                                for two channels.
+ *              - @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] docs: sound: describe 'chan_map' member in snd_dec_opus

Posted by Bagas Sanjaya 4 months, 1 week ago

On Fri, Sep 26, 2025 at 04:26:58PM +0000, Kriish Sharma wrote:
> diff --git a/include/uapi/sound/compress_params.h b/include/uapi/sound/compress_params.h
> index faf4fa911f7f..e90e2f40732a 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:
> + *              - @stream_count: Number of streams encoded in each Ogg packet.
> + *              - @coupled_count: Number of streams whose decoders are used
> + *                                for two channels.
> + *              - @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.
>   */
 
kernel-doc also supports documenting nested structs in this case:

---- >8 ----
diff --git a/include/uapi/sound/compress_params.h b/include/uapi/sound/compress_params.h
index e90e2f40732a0d..6398a253add5fb 100644
--- a/include/uapi/sound/compress_params.h
+++ b/include/uapi/sound/compress_params.h
@@ -337,13 +337,13 @@ struct snd_dec_ape {
  * are expected; values 2..255 are not recommended for playback.
  *
  * @chan_map: Optional channel mapping table. Describes mapping of opus streams
- *            to decoded channels. Fields:
- *              - @stream_count: Number of streams encoded in each Ogg packet.
- *              - @coupled_count: Number of streams whose decoders are used
- *                                for two channels.
- *              - @channel_map: Which decoded channel to be used for each one.
- *                              Supports only mapping families 0 and 1,
- *                              max number of channels is 8.
+ *            to decoded channels.
+ * @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.
  */

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] docs: sound: describe 'chan_map' member in snd_dec_opus

Posted by Takashi Iwai 4 months, 1 week ago

On Fri, 26 Sep 2025 18:26:58 +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.
> 
> Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>

Adding Alexey to Cc, as it was added by his patch.

If any, please resubmit with a proper subject line (e.g. "ALSA:
compress: ....") as well as the Fixes tag pointing to the affecting
commit.


thanks,

Takashi

> ---
>  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..e90e2f40732a 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:
> + *              - @stream_count: Number of streams encoded in each Ogg packet.
> + *              - @coupled_count: Number of streams whose decoders are used
> + *                                for two channels.
> + *              - @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] docs: sound: describe 'chan_map' member in snd_dec_opus

Posted by Bagas Sanjaya 4 months, 1 week ago

On Sat, Sep 27, 2025 at 10:17:34AM +0200, Takashi Iwai wrote:
> On Fri, 26 Sep 2025 18:26:58 +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.
> > 
> > Signed-off-by: Kriish Sharma <kriish.sharma2006@gmail.com>
> 
> Adding Alexey to Cc, as it was added by his patch.
> 
> If any, please resubmit with a proper subject line (e.g. "ALSA:
> compress: ....") as well as the Fixes tag pointing to the affecting
> commit.

In this case, the Fixes: tag should be:

Fixes: 5d36370f3431 ("ALSA: compress: add raw opus codec define and opus decoder structs")

Thanks.

-- 
An old man doll... just what I always wanted! - Clara