diff mbox series

[FFmpeg-devel,2/2] all: harmonise "{Decoding, Encoding, Audio, Video}:" comments

Message ID 20240229162424.850294-3-ffmpeg-devel@pileofstuff.org
State New
Headers show
Series Harmonise comments about ownership/meaning | expand

Checks

Context Check Description
yinshiyou/make_loongarch64 success Make finished
yinshiyou/make_fate_loongarch64 success Make fate finished
andriy/make_x86 success Make finished
andriy/make_fate_x86 success Make fate finished

Commit Message

Andrew Sayers Feb. 29, 2024, 4:23 p.m. UTC 
There seems to be a convention for documenting meanings:

    /**
     * Encoding: (meaning in encoding context)
     * Decoding: (meaning in decoding context)
     */

At a glance, these are confusingly similar to ownership comments.
They are also rendered by doxygen as long, hard-to-read paragraphs.

Reformat these comments to be more visually distinct and readable.
---
 libavcodec/avcodec.h   | 19 +++++++++++++------
 libavformat/avformat.h | 22 +++++++++++++++-------
 2 files changed, 28 insertions(+), 13 deletions(-)
diff mbox series

Patch

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 43859251cc..e2193f1d00 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -586,16 +586,23 @@  typedef struct AVCodecContext {
     /**
      * Codec delay.
      *
-     * Encoding: Number of frames delay there will be from the encoder input to
-     *           the decoder output. (we assume the decoder matches the spec)
-     * Decoding: Number of frames delay in addition to what a standard decoder
-     *           as specified in the spec would produce.
+     * *Encoding:*
+     *
+     *   Number of frames delay there will be from the encoder input to
+     *   the decoder output. (we assume the decoder matches the spec).
+     *
+     * *Decoding:*
+     *
+     *   Number of frames delay in addition to what a standard decoder
+     *   as specified in the spec would produce.
+     *
+     * *Video:*
      *
-     * Video:
      *   Number of frames the decoded output will be delayed relative to the
      *   encoded input.
      *
-     * Audio:
+     * *Audio:*
+     *
      *   For encoding, this field is unused (see initial_padding).
      *
      *   For decoding, this is the number of samples the decoder needs to
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 35b7f78ec7..be97947bd1 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -882,19 +882,27 @@  typedef struct AVStream {
     AVRational time_base;
 
     /**
-     * Decoding: pts of the first frame of the stream in presentation order, in stream time base.
-     * Only set this if you are absolutely 100% sure that the value you set
-     * it to really is the pts of the first frame.
-     * This may be undefined (AV_NOPTS_VALUE).
+     * *Decoding:*
+     *
+     *   pts of the first frame of the stream in presentation order, in stream time base.
+     *
+     *   Only set this if you are absolutely 100% sure that the value you set
+     *   it to really is the pts of the first frame.
+     *
+     *   This may be undefined (AV_NOPTS_VALUE).
+     *
      * @note The ASF header does NOT contain a correct start_time the ASF
      * demuxer must NOT set this.
      */
     int64_t start_time;
 
     /**
-     * Decoding: duration of the stream, in stream time base.
-     * If a source file does not specify a duration, but does specify
-     * a bitrate, this value will be estimated from bitrate and file size.
+     * *Decoding:*
+     *
+     *   Duration of the stream, in stream time base.
+     *
+     *   If a source file does not specify a duration, but does specify
+     *   a bitrate, this value will be estimated from bitrate and file size.
      *
      * - decoding: set by libavformat
      * - encoding: may be set by the caller before avformat_write_header() to