* [FFmpeg-devel] [PATCH 6/7] avformat/avformat: Improve doxy style
2022-09-15 1:52 [FFmpeg-devel] [PATCH 4/7] avutil: Fix mismatching argument names Marvin Scholz
2022-09-15 1:52 ` [FFmpeg-devel] [PATCH 5/7] swresample/swresample: " Marvin Scholz
@ 2022-09-15 1:53 ` Marvin Scholz
2022-09-15 1:53 ` [FFmpeg-devel] [PATCH 7/7] avcodec/avcodec: Escape Doxygen reference Marvin Scholz
2 siblings, 0 replies; 6+ messages in thread
From: Marvin Scholz @ 2022-09-15 1:53 UTC (permalink / raw)
To: ffmpeg-devel; +Cc: Marvin Scholz
Mostly re-indenting and adding some missing references.
---
libavformat/avformat.h | 180 +++++++++++++++++++++++------------------
1 file changed, 103 insertions(+), 77 deletions(-)
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index c695cfc6de..1d97d56ac5 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -1898,8 +1898,8 @@ const AVOutputFormat *av_muxer_iterate(void **opaque);
/**
* Iterate over all registered demuxers.
*
- * @param opaque a pointer where libavformat will store the iteration state. Must
- * point to NULL to start the iteration.
+ * @param opaque a pointer where libavformat will store the iteration state.
+ * Must point to NULL to start the iteration.
*
* @return the next registered demuxer or NULL when the iteration is
* finished
@@ -1957,12 +1957,13 @@ AVStream *avformat_new_stream(AVFormatContext *s, const AVCodec *c);
/**
* Wrap an existing array as stream side data.
*
- * @param st stream
+ * @param st stream
* @param type side information type
* @param data the side data array. It must be allocated with the av_malloc()
* family of functions. The ownership of the data is transferred to
* st.
* @param size side information size
+ *
* @return zero on success, a negative AVERROR code on failure. On failure,
* the stream is unchanged and the data remains owned by the caller.
*/
@@ -1973,8 +1974,9 @@ int av_stream_add_side_data(AVStream *st, enum AVPacketSideDataType type,
* Allocate new information from stream.
*
* @param stream stream
- * @param type desired side information type
- * @param size side information size
+ * @param type desired side information type
+ * @param size side information size
+ *
* @return pointer to fresh allocated data or NULL otherwise
*/
uint8_t *av_stream_new_side_data(AVStream *stream,
@@ -1983,9 +1985,10 @@ uint8_t *av_stream_new_side_data(AVStream *stream,
* Get side information from stream.
*
* @param stream stream
- * @param type desired side information type
- * @param size If supplied, *size will be set to the size of the side data
- * or to zero if the desired side data is not present.
+ * @param type desired side information type
+ * @param size If supplied, *size will be set to the size of the side data
+ * or to zero if the desired side data is not present.
+ *
* @return pointer to data if present or NULL otherwise
*/
uint8_t *av_stream_get_side_data(const AVStream *stream,
@@ -2003,16 +2006,17 @@ AVProgram *av_new_program(AVFormatContext *s, int id);
* avformat_free_context() can be used to free the context and
* everything allocated by the framework within it.
*
- * @param ctx pointee is set to the created format context, or to NULL in
- * case of failure
- * @param oformat format to use for allocating the context, if NULL
- * format_name and filename are used instead
- * @param format_name the name of output format to use for allocating the
- * context, if NULL filename is used instead
- * @param filename the name of the filename to use for allocating the
- * context, may be NULL
- * @return >= 0 in case of success, a negative AVERROR code in case of
- * failure
+ * @param ctx pointee is set to the created format context,
+ * or to NULL in case of failure
+ * @param oformat format to use for allocating the context, if NULL
+ * format_name and filename are used instead
+ * @param format_name the name of output format to use for allocating the
+ * context, if NULL filename is used instead
+ * @param filename the name of the filename to use for allocating the
+ * context, may be NULL
+ *
+ * @return >= 0 in case of success, a negative AVERROR code in case of
+ * failure
*/
int avformat_alloc_output_context2(AVFormatContext **ctx, const AVOutputFormat *oformat,
const char *format_name, const char *filename);
@@ -2067,15 +2071,16 @@ const AVInputFormat *av_probe_input_format3(const AVProbeData *pd,
* attempt is made. When the maximum probe size is reached, the input format
* with the highest score is returned.
*
- * @param pb the bytestream to probe
- * @param fmt the input format is put here
- * @param url the url of the stream
- * @param logctx the log context
- * @param offset the offset within the bytestream to probe from
+ * @param pb the bytestream to probe
+ * @param fmt the input format is put here
+ * @param url the url of the stream
+ * @param logctx the log context
+ * @param offset the offset within the bytestream to probe from
* @param max_probe_size the maximum probe buffer size (zero for default)
+ *
* @return the score in case of success, a negative value corresponding to an
* the maximal score is AVPROBE_SCORE_MAX
- * AVERROR code otherwise
+ * AVERROR code otherwise
*/
int av_probe_input_buffer2(AVIOContext *pb, const AVInputFormat **fmt,
const char *url, void *logctx,
@@ -2092,16 +2097,19 @@ int av_probe_input_buffer(AVIOContext *pb, const AVInputFormat **fmt,
* Open an input stream and read the header. The codecs are not opened.
* The stream must be closed with avformat_close_input().
*
- * @param ps Pointer to user-supplied AVFormatContext (allocated by avformat_alloc_context).
- * May be a pointer to NULL, in which case an AVFormatContext is allocated by this
- * function and written into ps.
- * Note that a user-supplied AVFormatContext will be freed on failure.
- * @param url URL of the stream to open.
- * @param fmt If non-NULL, this parameter forces a specific input format.
- * Otherwise the format is autodetected.
- * @param options A dictionary filled with AVFormatContext and demuxer-private options.
- * On return this parameter will be destroyed and replaced with a dict containing
- * options that were not found. May be NULL.
+ * @param ps Pointer to user-supplied AVFormatContext (allocated by
+ * avformat_alloc_context). May be a pointer to NULL, in
+ * which case an AVFormatContext is allocated by this
+ * function and written into ps.
+ * Note that a user-supplied AVFormatContext will be freed
+ * on failure.
+ * @param url URL of the stream to open.
+ * @param fmt If non-NULL, this parameter forces a specific input format.
+ * Otherwise the format is autodetected.
+ * @param options A dictionary filled with AVFormatContext and demuxer-private
+ * options.
+ * On return this parameter will be destroyed and replaced with
+ * a dict containing options that were not found. May be NULL.
*
* @return 0 on success, a negative AVERROR on failure.
*
@@ -2140,6 +2148,7 @@ int avformat_find_stream_info(AVFormatContext *ic, AVDictionary **options);
* @param last the last found program, the search will start after this
* program, or from the beginning if it is NULL
* @param s stream index
+ *
* @return the next program which belongs to s, NULL if no program is found or
* the last program is not among the programs of ic.
*/
@@ -2164,10 +2173,12 @@ void av_program_add_stream_index(AVFormatContext *ac, int progid, unsigned int i
* @param decoder_ret if non-NULL, returns the decoder for the
* selected stream
* @param flags flags; none are currently defined
+ *
* @return the non-negative stream number in case of success,
* AVERROR_STREAM_NOT_FOUND if no stream with the requested type
* could be found,
* AVERROR_DECODER_NOT_FOUND if streams were found but no decoder
+ *
* @note If av_find_best_stream returns successfully and decoder_ret is not
* NULL, then *decoder_ret is guaranteed to be set to a valid AVCodec.
*/
@@ -2211,13 +2222,14 @@ int av_read_frame(AVFormatContext *s, AVPacket *pkt);
* Seek to the keyframe at timestamp.
* 'timestamp' in 'stream_index'.
*
- * @param s media file handle
- * @param stream_index If stream_index is (-1), a default
- * stream is selected, and timestamp is automatically converted
- * from AV_TIME_BASE units to the stream specific time_base.
- * @param timestamp Timestamp in AVStream.time_base units
- * or, if no stream is specified, in AV_TIME_BASE units.
- * @param flags flags which select direction and seeking mode
+ * @param s media file handle
+ * @param stream_index If stream_index is (-1), a default stream is selected,
+ * and timestamp is automatically converted from
+ * AV_TIME_BASE units to the stream specific time_base.
+ * @param timestamp Timestamp in AVStream.time_base units or, if no stream
+ * is specified, in AV_TIME_BASE units.
+ * @param flags flags which select direction and seeking mode
+ *
* @return >= 0 on success
*/
int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
@@ -2239,12 +2251,12 @@ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
* keyframes (this may not be supported by all demuxers).
* If flags contain AVSEEK_FLAG_BACKWARD, it is ignored.
*
- * @param s media file handle
+ * @param s media file handle
* @param stream_index index of the stream which is used as time base reference
- * @param min_ts smallest acceptable timestamp
- * @param ts target timestamp
- * @param max_ts largest acceptable timestamp
- * @param flags flags
+ * @param min_ts smallest acceptable timestamp
+ * @param ts target timestamp
+ * @param max_ts largest acceptable timestamp
+ * @param flags flags
* @return >=0 on success, error code otherwise
*
* @note This is part of the new seek API which is still under construction.
@@ -2308,16 +2320,22 @@ void avformat_close_input(AVFormatContext **s);
* Allocate the stream private data and write the stream header to
* an output media file.
*
- * @param s Media file handle, must be allocated with avformat_alloc_context().
- * Its oformat field must be set to the desired output format;
- * Its pb field must be set to an already opened AVIOContext.
- * @param options An AVDictionary filled with AVFormatContext and muxer-private options.
- * On return this parameter will be destroyed and replaced with a dict containing
- * options that were not found. May be NULL.
- *
- * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec had not already been fully initialized in avformat_init,
- * AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec had already been fully initialized in avformat_init,
- * negative AVERROR on failure.
+ * @param s Media file handle, must be allocated with
+ * avformat_alloc_context().
+ * Its \ref AVFormatContext.oformat "oformat" field must be set
+ * to the desired output format;
+ * Its \ref AVFormatContext.pb "pb" field must be set to an
+ * already opened ::AVIOContext.
+ * @param options An ::AVDictionary filled with AVFormatContext and
+ * muxer-private options.
+ * On return this parameter will be destroyed and replaced with
+ * a dict containing options that were not found. May be NULL.
+ *
+ * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec had not already been
+ * fully initialized in avformat_init_output().
+ * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec had already been fully
+ * initialized in avformat_init_output().
+ * @retval AVERROR A negative AVERROR on failure.
*
* @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output.
*/
@@ -2326,20 +2344,26 @@ int avformat_write_header(AVFormatContext *s, AVDictionary **options);
/**
* Allocate the stream private data and initialize the codec, but do not write the header.
- * May optionally be used before avformat_write_header to initialize stream parameters
+ * May optionally be used before avformat_write_header() to initialize stream parameters
* before actually writing the header.
- * If using this function, do not pass the same options to avformat_write_header.
- *
- * @param s Media file handle, must be allocated with avformat_alloc_context().
- * Its oformat field must be set to the desired output format;
- * Its pb field must be set to an already opened AVIOContext.
- * @param options An AVDictionary filled with AVFormatContext and muxer-private options.
- * On return this parameter will be destroyed and replaced with a dict containing
- * options that were not found. May be NULL.
- *
- * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec requires avformat_write_header to fully initialize,
- * AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec has been fully initialized,
- * negative AVERROR on failure.
+ * If using this function, do not pass the same options to avformat_write_header().
+ *
+ * @param s Media file handle, must be allocated with
+ * avformat_alloc_context().
+ * Its \ref AVFormatContext.oformat "oformat" field must be set
+ * to the desired output format;
+ * Its \ref AVFormatContext.pb "pb" field must be set to an
+ * already opened ::AVIOContext.
+ * @param options An ::AVDictionary filled with AVFormatContext and
+ * muxer-private options.
+ * On return this parameter will be destroyed and replaced with
+ * a dict containing options that were not found. May be NULL.
+ *
+ * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec requires
+ * avformat_write_header to fully initialize.
+ * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec has been fully
+ * initialized.
+ * @retval AVERROR Anegative AVERROR on failure.
*
* @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header.
*/
@@ -2484,11 +2508,11 @@ int av_write_trailer(AVFormatContext *s);
* there is no match.
*
* @param short_name if non-NULL checks if short_name matches with the
- * names of the registered formats
- * @param filename if non-NULL checks if filename terminates with the
- * extensions of the registered formats
- * @param mime_type if non-NULL checks if mime_type matches with the
- * MIME type of the registered formats
+ * names of the registered formats
+ * @param filename if non-NULL checks if filename terminates with the
+ * extensions of the registered formats
+ * @param mime_type if non-NULL checks if mime_type matches with the
+ * MIME type of the registered formats
*/
const AVOutputFormat *av_guess_format(const char *short_name,
const char *filename,
@@ -2512,9 +2536,11 @@ enum AVCodecID av_guess_codec(const AVOutputFormat *fmt, const char *short_name,
* time_base units
* @param[out] wall absolute time when that packet whas output,
* in microsecond
- * @return 0 if OK, AVERROR(ENOSYS) if the format does not support it
- * Note: some formats or devices may not allow to measure dts and wall
- * atomically.
+ * @retval 0 Success
+ * @retval AVERROR(ENOSYS) The format does not support it
+ *
+ * @note Some formats or devices may not allow to measure dts and wall
+ * atomically.
*/
int av_get_output_timestamp(struct AVFormatContext *s, int stream,
int64_t *dts, int64_t *wall);
--
2.37.0 (Apple Git-136)
_______________________________________________
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".
^ permalink raw reply [flat|nested] 6+ messages in thread