[FFmpeg-devel] [PATCH] AVCodec documentation style improvements (PR #20312)

[Marvin Scholz via ffmpeg-devel <ffmpeg-devel@ffmpeg.org>]

PR #20312 opened by Marvin Scholz (ePirat)
URL: https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/20312
Patch URL: https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/20312.patch

Improves grouping and brief descriptions for AVCodecParameters.


From 0e610267507db4b657669e6da442ed58798a8680 Mon Sep 17 00:00:00 2001
From: Marvin Scholz <epirat07@gmail.com>
Date: Fri, 21 Mar 2025 04:43:35 +0100
Subject: [PATCH 1/2] doc: style changes for the AVCodecParameters

Mostly adding references and making the video/audio only
annotations not be the brief description.
---
 libavcodec/codec_par.h | 123 ++++++++++++++++++++++++++++-------------
 1 file changed, 84 insertions(+), 39 deletions(-)

diff --git a/libavcodec/codec_par.h b/libavcodec/codec_par.h
index 64b01f7e02..1cc2787c4b 100644
--- a/libavcodec/codec_par.h
+++ b/libavcodec/codec_par.h
@@ -33,16 +33,18 @@
 #include "packet.h"
 
 /**
- * @addtogroup lavc_core
+ * @defgroup lavc_codec_params Codec parameters
+ * @ingroup lavc_core
  * @{
  */
 
 /**
  * This struct describes the properties of an encoded stream.
  *
- * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must
- * be allocated with avcodec_parameters_alloc() and freed with
- * avcodec_parameters_free().
+ * @note
+ * The `sizeof(AVCodecParameters)` is not a part of the public ABI,
+ * therefore this struct must be allocated with ::avcodec_parameters_alloc()
+ * and freed with ::avcodec_parameters_free().
  */
 typedef struct AVCodecParameters {
     /**
@@ -61,9 +63,9 @@ typedef struct AVCodecParameters {
     /**
      * Extra binary data needed for initializing the decoder, codec-dependent.
      *
-     * Must be allocated with av_malloc() and will be freed by
-     * avcodec_parameters_free(). The allocated size of extradata must be at
-     * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding
+     * Must be allocated with ::av_malloc() and will be freed by
+     * ::avcodec_parameters_free(). The allocated size of extradata must be at
+     * least ::extradata_size + ::AV_INPUT_BUFFER_PADDING_SIZE, with the padding
      * bytes zeroed.
      */
     uint8_t *extradata;
@@ -75,19 +77,19 @@ typedef struct AVCodecParameters {
     /**
      * Additional data associated with the entire stream.
      *
-     * Should be allocated with av_packet_side_data_new() or
-     * av_packet_side_data_add(), and will be freed by avcodec_parameters_free().
+     * Should be allocated with ::av_packet_side_data_new() or
+     * ::av_packet_side_data_add(), and will be freed by ::avcodec_parameters_free().
      */
     AVPacketSideData *coded_side_data;
 
     /**
-     * Amount of entries in @ref coded_side_data.
+     * Amount of entries in ::coded_side_data.
      */
     int nb_coded_side_data;
 
     /**
-     * - video: the pixel format, the value corresponds to enum AVPixelFormat.
-     * - audio: the sample format, the value corresponds to enum AVSampleFormat.
+     * - Video: the pixel format, the value corresponds to enum ::AVPixelFormat.
+     * - Audio: the sample format, the value corresponds to enum ::AVSampleFormat.
      */
     int format;
 
@@ -103,22 +105,27 @@ typedef struct AVCodecParameters {
      * formats to actually decode them. It's the number of bits for one sample in
      * the actual coded bitstream.
      *
-     * This could be for example 4 for ADPCM
-     * For PCM formats this matches bits_per_raw_sample
-     * Can be 0
+     * This could be for example 4 for ADPCM.
+     * For PCM formats this matches ::bits_per_raw_sample.
+     *
+     * Can be 0.
      */
     int bits_per_coded_sample;
 
     /**
-     * This is the number of valid bits in each output sample. If the
-     * sample format has more bits, the least significant bits are additional
+     * The number of valid bits in each output sample.
+     *
+     * If the sample format has more bits, the least significant bits are additional
      * padding bits, which are always 0. Use right shifts to reduce the sample
-     * to its actual size. For example, audio formats with 24 bit samples will
-     * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32.
-     * To get the original sample use "(int32_t)sample >> 8"."
+     * to its actual size.
+     *
+     * For example, audio formats with 24 bit samples will have ::bits_per_raw_sample
+     * set to 24, and ::format set to ::AV_SAMPLE_FMT_S32. To get the original sample
+     * use: `(int32_t)sample >> 8`.
      *
      * For ADPCM this might be 12 or 16 or similar
-     * Can be 0
+     *
+     * Can be 0.
      */
     int bits_per_raw_sample;
 
@@ -129,9 +136,17 @@ typedef struct AVCodecParameters {
     int level;
 
     /**
-     * Video only. The dimensions of the video frame in pixels.
+     * The width of the video frame in pixels
+     *
+     * Video only.
      */
     int width;
+
+    /**
+     * The height of the video frame in pixels.
+     *
+     * Video only.
+     */
     int height;
 
     /**
@@ -145,7 +160,7 @@ typedef struct AVCodecParameters {
 
     /**
      * Video only. Number of frames per second, for streams with constant frame
-     * durations. Should be set to { 0, 1 } when some frames have differing
+     * durations. Should be set to `{ 0, 1 }` when some frames have differing
      * durations or if the value is not known.
      *
      * @note This field corresponds to values that are stored in codec-level
@@ -156,12 +171,16 @@ typedef struct AVCodecParameters {
     AVRational framerate;
 
     /**
-     * Video only. The order of the fields in interlaced video.
+     * The order of the fields in interlaced video.
+     *
+     * Video only.
      */
     enum AVFieldOrder                  field_order;
 
     /**
-     * Video only. Additional colorspace characteristics.
+     * Additional colorspace characteristics.
+     *
+     * Video only.
      */
     enum AVColorRange                  color_range;
     enum AVColorPrimaries              color_primaries;
@@ -170,65 +189,89 @@ typedef struct AVCodecParameters {
     enum AVChromaLocation              chroma_location;
 
     /**
-     * Video only. Number of delayed frames.
+     * Number of delayed frames.
+     *
+     * Video only.
      */
     int video_delay;
 
     /**
-     * Audio only. The channel layout and number of channels.
+     * The channel layout and number of channels.
+     *
+     * Audio only.
      */
     AVChannelLayout ch_layout;
     /**
-     * Audio only. The number of audio samples per second.
+     * The number of audio samples per second.
+     *
+     * Audio only.
      */
     int      sample_rate;
     /**
-     * Audio only. The number of bytes per coded audio frame, required by some
-     * formats.
+     * The number of bytes per coded audio frame, required by some formats.
+     *
+     * Audio only.
      *
      * Corresponds to nBlockAlign in WAVEFORMATEX.
      */
     int      block_align;
     /**
-     * Audio only. Audio frame size, if known. Required by some formats to be static.
+     * Audio frame size, if known. Required by some formats to be static.
+     *
+     * Audio only.
      */
     int      frame_size;
 
     /**
-     * Audio only. The amount of padding (in samples) inserted by the encoder at
+     * Number of padding audio samples at the start.
+     *
+     * The amount of padding (in samples) inserted by the encoder at
      * the beginning of the audio. I.e. this number of leading decoded samples
      * must be discarded by the caller to get the original audio without leading
      * padding.
+     *
+     * Audio only.
      */
     int initial_padding;
     /**
-     * Audio only. The amount of padding (in samples) appended by the encoder to
+     * Number of padding audio samples at the end.
+     *
+     * The amount of padding (in samples) appended by the encoder to
      * the end of the audio. I.e. this number of decoded samples must be
      * discarded by the caller from the end of the stream to get the original
      * audio without any trailing padding.
+     *
+     * Audio only.
      */
     int trailing_padding;
     /**
-     * Audio only. Number of samples to skip after a discontinuity.
+     * Number of audio samples to skip after a discontinuity.
+     *
+     * Audio only.
      */
     int seek_preroll;
 } AVCodecParameters;
 
+/**
+ * @relates AVCodecParameters
+ * @{
+ */
+
 /**
  * Allocate a new AVCodecParameters and set its fields to default values
  * (unknown/invalid/0). The returned struct must be freed with
- * avcodec_parameters_free().
+ * ::avcodec_parameters_free().
  */
 AVCodecParameters *avcodec_parameters_alloc(void);
 
 /**
  * Free an AVCodecParameters instance and everything associated with it and
- * write NULL to the supplied pointer.
+ * write `NULL` to the supplied pointer.
  */
 void avcodec_parameters_free(AVCodecParameters **par);
 
 /**
- * Copy the contents of src to dst. Any allocated fields in dst are freed and
+ * Copy the contents of \p src to \p dst. Any allocated fields in dst are freed and
  * replaced with newly allocated duplicates of the corresponding fields in src.
  *
  * @return >= 0 on success, a negative AVERROR code on failure.
@@ -236,11 +279,13 @@ void avcodec_parameters_free(AVCodecParameters **par);
 int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
 
 /**
- * This function is the same as av_get_audio_frame_duration(), except it works
- * with AVCodecParameters instead of an AVCodecContext.
+ * This function is the same as ::av_get_audio_frame_duration(), except it works
+ * with ::AVCodecParameters instead of an ::AVCodecContext.
  */
 int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes);
 
+/** @} */
+
 /**
  * @}
  */
-- 
2.49.1


From 77c8a184ef3be96d1da3f00d71fb8b44c0974d44 Mon Sep 17 00:00:00 2001
From: Marvin Scholz <epirat07@gmail.com>
Date: Fri, 21 Mar 2025 04:44:31 +0100
Subject: [PATCH 2/2] doc: mark functions related to AVCodecParameters

This makes these functions appear in the AVCodecParameters
documentation page, so they are easier to find.
---
 libavcodec/avcodec.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 108df5a24e..17b18cbf74 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2139,6 +2139,8 @@ const AVClass *avcodec_get_subtitle_rect_class(void);
  * of the corresponding fields in codec.
  *
  * @return >= 0 on success, a negative AVERROR code on failure
+ *
+ * @relates AVCodecParameters
  */
 int avcodec_parameters_from_context(struct AVCodecParameters *par,
                                     const AVCodecContext *codec);
@@ -2150,6 +2152,8 @@ int avcodec_parameters_from_context(struct AVCodecParameters *par,
  * Fields in codec that do not have a counterpart in par are not touched.
  *
  * @return >= 0 on success, a negative AVERROR code on failure.
+ *
+ * @relates AVCodecParameters
  */
 int avcodec_parameters_to_context(AVCodecContext *codec,
                                   const struct AVCodecParameters *par);
-- 
2.49.1

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".