[FFmpeg-devel] [PATCH 1/2] avformat: harmonise "- {decoding, encoding, demuxing, muxing}: " comments

Andrew Sayers ffmpeg-devel at pileofstuff.org
Thu Feb 29 18:23:06 EET 2024


There seems to be a convention for documenting ownership:

    /**
     * - encoding: (who sets this in encoding context)
     * - decoding: (who sets this in decoding context)
     */
    int foo;

Ensure all such comments start with a "-" and use lower case,
so doxygen formats them as a bulleted lists instead of one
long paragraph.

Signed-off-by: Andrew Sayers <ffmpeg-devel at pileofstuff.org>
---
 libavformat/avformat.h | 67 +++++++++++++++++++++---------------------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index f4506f4cf1..35b7f78ec7 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -849,8 +849,8 @@ typedef struct AVStream {
     int index;    /**< stream index in AVFormatContext */
     /**
      * Format-specific stream ID.
-     * decoding: set by libavformat
-     * encoding: set by the user, replaced by libavformat if left unset
+     * - decoding: set by libavformat
+     * - encoding: set by the user, replaced by libavformat if left unset
      */
     int id;
 
@@ -871,13 +871,13 @@ typedef struct AVStream {
      * This is the fundamental unit of time (in seconds) in terms
      * of which frame timestamps are represented.
      *
-     * decoding: set by libavformat
-     * encoding: May be set by the caller before avformat_write_header() to
-     *           provide a hint to the muxer about the desired timebase. In
-     *           avformat_write_header(), the muxer will overwrite this field
-     *           with the timebase that will actually be used for the timestamps
-     *           written into the file (which may or may not be related to the
-     *           user-provided one, depending on the format).
+     * - decoding: set by libavformat
+     * - encoding: May be set by the caller before avformat_write_header() to
+     *             provide a hint to the muxer about the desired timebase. In
+     *             avformat_write_header(), the muxer will overwrite this field
+     *             with the timebase that will actually be used for the timestamps
+     *             written into the file (which may or may not be related to the
+     *             user-provided one, depending on the format).
      */
     AVRational time_base;
 
@@ -896,8 +896,9 @@ typedef struct AVStream {
      * If a source file does not specify a duration, but does specify
      * a bitrate, this value will be estimated from bitrate and file size.
      *
-     * Encoding: May be set by the caller before avformat_write_header() to
-     * provide a hint to the muxer about the estimated duration.
+     * - decoding: set by libavformat
+     * - encoding: may be set by the caller before avformat_write_header() to
+     *             provide a hint to the muxer about the estimated duration.
      */
     int64_t duration;
 
@@ -935,8 +936,8 @@ typedef struct AVStream {
      * For streams with AV_DISPOSITION_ATTACHED_PIC disposition, this packet
      * will contain the attached picture.
      *
-     * decoding: set by libavformat, must not be modified by the caller.
-     * encoding: unused
+     * - decoding: set by libavformat, must not be modified by the caller.
+     * - encoding: unused
      */
     AVPacket attached_pic;
 
@@ -1203,16 +1204,16 @@ typedef struct AVStreamGroup {
     /**
      * Group type-specific group ID.
      *
-     * decoding: set by libavformat
-     * encoding: may set by the user
+     * - decoding: set by libavformat
+     * - encoding: may set by the user
      */
     int64_t id;
 
     /**
      * Group type
      *
-     * decoding: set by libavformat on group creation
-     * encoding: set by avformat_stream_group_create()
+     * - decoding: set by libavformat on group creation
+     * - encoding: set by avformat_stream_group_create()
      */
     enum AVStreamGroupParamsType type;
 
@@ -1534,19 +1535,19 @@ typedef struct AVFormatContext {
 
     /**
      * Forced video codec_id.
-     * Demuxing: Set by user.
+     * - demuxing: Set by user.
      */
     enum AVCodecID video_codec_id;
 
     /**
      * Forced audio codec_id.
-     * Demuxing: Set by user.
+     * - demuxing: Set by user.
      */
     enum AVCodecID audio_codec_id;
 
     /**
      * Forced subtitle codec_id.
-     * Demuxing: Set by user.
+     * - demuxing: Set by user.
      */
     enum AVCodecID subtitle_codec_id;
 
@@ -1622,11 +1623,11 @@ typedef struct AVFormatContext {
     /**
      * Custom interrupt callbacks for the I/O layer.
      *
-     * demuxing: set by the user before avformat_open_input().
-     * muxing: set by the user before avformat_write_header()
-     * (mainly useful for AVFMT_NOFILE formats). The callback
-     * should also be passed to avio_open2() if it's used to
-     * open the file.
+     * - demuxing: set by the user before avformat_open_input().
+     * - muxing: set by the user before avformat_write_header()
+     *           (mainly useful for AVFMT_NOFILE formats). The callback
+     *           should also be passed to avio_open2() if it's used to
+     *           open the file.
      */
     AVIOInterruptCB interrupt_callback;
 
@@ -1828,7 +1829,7 @@ typedef struct AVFormatContext {
      * Forced video codec.
      * This allows forcing a specific decoder, even when there are multiple with
      * the same codec_id.
-     * Demuxing: Set by user
+     * - demuxing: Set by user
      */
     const struct AVCodec *video_codec;
 
@@ -1836,7 +1837,7 @@ typedef struct AVFormatContext {
      * Forced audio codec.
      * This allows forcing a specific decoder, even when there are multiple with
      * the same codec_id.
-     * Demuxing: Set by user
+     * - demuxing: Set by user
      */
     const struct AVCodec *audio_codec;
 
@@ -1844,7 +1845,7 @@ typedef struct AVFormatContext {
      * Forced subtitle codec.
      * This allows forcing a specific decoder, even when there are multiple with
      * the same codec_id.
-     * Demuxing: Set by user
+     * - demuxing: Set by user
      */
     const struct AVCodec *subtitle_codec;
 
@@ -1852,14 +1853,14 @@ typedef struct AVFormatContext {
      * Forced data codec.
      * This allows forcing a specific decoder, even when there are multiple with
      * the same codec_id.
-     * Demuxing: Set by user
+     * - demuxing: Set by user
      */
     const struct AVCodec *data_codec;
 
     /**
      * Number of bytes to be written as padding in a metadata header.
-     * Demuxing: Unused.
-     * Muxing: Set by user.
+     * - demuxing: Unused.
+     * - muxing: Set by user.
      */
     int metadata_header_padding;
 
@@ -1876,7 +1877,7 @@ typedef struct AVFormatContext {
 
     /**
      * Output timestamp offset, in microseconds.
-     * Muxing: set by user
+     * - muxing: set by user
      */
     int64_t output_ts_offset;
 
@@ -1890,7 +1891,7 @@ typedef struct AVFormatContext {
 
     /**
      * Forced Data codec_id.
-     * Demuxing: Set by user.
+     * - demuxing: Set by user.
      */
     enum AVCodecID data_codec_id;
 
-- 
2.43.0



More information about the ffmpeg-devel mailing list