From patchwork Thu Sep 15 01:53:00 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 37919 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3b1c:b0:96:9ee8:5cfd with SMTP id c28csp26409pzh; Wed, 14 Sep 2022 18:53:56 -0700 (PDT) X-Google-Smtp-Source: AA6agR6gQj/wFhbDtio+zMJDuL94VlXymSzizbm4acm8NJfn1TcAMHJ4gPaA/ljIDh4H74Ngd8Mt X-Received: by 2002:a17:906:9fc1:b0:761:9192:504f with SMTP id hj1-20020a1709069fc100b007619192504fmr27295814ejc.116.1663206835982; Wed, 14 Sep 2022 18:53:55 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1663206835; cv=none; d=google.com; s=arc-20160816; b=mVB/x+0UfZ3gG8+g3vKlDzleFrXXlhdE7gsKtCONNOs1qTRksTJ0rfuBCHWnFLChA5 y/Wm0VmolYMezjHKF8N8VWQHa32GjUvxbvpka7NN0qqVLnm0BXkzUvrWSyDQAb35HBD0 XkCyGAL+8zKQViJD506poGnwYvdfoBwqDw3/sl+cyvwwaKRp+oVZC/QYDxb9JjlzzHid Jcayaa/XKvJN31tHCCaq0RgCPXEU+N7vuc2bMmor8T23sh4+x57sbNYez2pc6UTvdn5D FvO5dkt1pMw5BSRVVtmMdjVVkJ3JCBdKCxc1h4ynNuhMPuVyOq9nt69iitb4K0EJm/vh 6HTg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature:delivered-to; bh=zL4sWPEaj0B3K4EhUdeISEm/5+PpAfw9gHsO+d5hPDQ=; b=KPlG1SDNcp2AmQa36nMNSgBx6RMEM5m4XuXJJTNaGRYfBVmh/nYp94qXPGb8HkNwgL D6RGB9AEnM8MDUSLoKi6BGtHQb05UxTkIun+xAvuhROafFkaxzyp10KoUfH/A9hURuVO N9j5q02uCI/U2mE9JhPlBe5xUtxXlnjUdbBlPOv0pu1bIB6+uq0wAFypxK2upvuRM0SD GhsKa3rziNC4rW7h41IVHhUytTgG0oEcP8ljzouiwXHl+DvPU9RVGB3Se8cqQ4l7j8Uq s1xImit3igEv7gH65t1Jz9yD0PgYPVaQwbNceyLFg4deBOHk2EGppw1nHi0tPGAPrNV7 Z/8Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=ebBnib05; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id h2-20020aa7c602000000b0044e8330487esi10712157edq.264.2022.09.14.18.53.55; Wed, 14 Sep 2022 18:53:55 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=ebBnib05; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 425D568BB37; Thu, 15 Sep 2022 04:53:34 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-wm1-f44.google.com (mail-wm1-f44.google.com [209.85.128.44]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 6879268B76F for ; Thu, 15 Sep 2022 04:53:26 +0300 (EEST) Received: by mail-wm1-f44.google.com with SMTP id h133-20020a1c218b000000b003b494ffc00bso31050wmh.0 for ; Wed, 14 Sep 2022 18:53:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=wLYnHglkepTFDqeEdl4n8vXjnkT5gb6SWHBZfelC0DE=; b=ebBnib05llMEdLCV1elNwzeB58md8BuqIy2eKgiuryoQgFyxOzA0LKwIoB5efgDGXl 9K08hIhE/xdOCkVAmAQZiqQ9MGDsBe0Fxrx61jY4onu6fYGj38EaSxUTjpYnObVKAuwY 9PKG9OkvJW1+lasqO+sPo1YM0RY4yzASrC+n1hYUWjLRgsfl8wCrj/8xNzRQRZ+PyHKy iKSY87S2a7+gibILLXCV3+iz7+oNi45I2gcZzynNw7zGPXYop07y8tuLvqxu4Xm2uEYB y/dYEISMiWSFQuwrR6mW3Ew0DZCYsgNKNi7g/H0EE4eAUXxPlqOj77nwl9s+NQ+HijQ0 38vw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date; bh=wLYnHglkepTFDqeEdl4n8vXjnkT5gb6SWHBZfelC0DE=; b=x5V/yPHKxUmiC2A2xOw2qYT77bzR9+XYvMtIw48QoCM1EzZ+HwxGYxNHeUMtYW6cEr lMGsZVHi2T7KlC9G3gxeUZkkeWFZR4lb6DTvY7anmrmBriww11YHoqgq9t7HbJcLtAlr 3uKr2xtEuAvJOlVdeiPklYb/5R8IvMGlTz+70D7i8jAvPn46bAChSC4vc6GMik1bsw39 Weu2qg+8BoIZiOzCNu+0LYVruW6RNKLa2ABs630IPj9lPu2jLv2L+z9pQiJurzGZT49q +/hS0jjlSWc18+jhbU5Isj/8Gr791DpRBf+ORV5iuWsqs0rJaQ3myIXW6XlWCt5PFT+i Q3TQ== X-Gm-Message-State: ACgBeo2ldWL3nP43IMdDHO5LP+AE721Vm+mGcra3x8YIsnVCMlUFl2MJ JTQPo1UK0dW27uDJ91Hv/Hl1QVj/GtxBbA== X-Received: by 2002:a7b:ce97:0:b0:3b3:4136:59fe with SMTP id q23-20020a7bce97000000b003b3413659femr5004214wmj.24.1663206805490; Wed, 14 Sep 2022 18:53:25 -0700 (PDT) Received: from MBP-von-Marvin.citadel.scalie.me (84-112-104-25.cable.dynamic.surfer.at. [84.112.104.25]) by smtp.gmail.com with ESMTPSA id x4-20020adfec04000000b002253604bbefsm823633wrn.75.2022.09.14.18.53.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 14 Sep 2022 18:53:25 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Thu, 15 Sep 2022 03:53:00 +0200 Message-Id: <20220915015301.34744-6-epirat07@gmail.com> X-Mailer: git-send-email 2.37.0 (Apple Git-136) In-Reply-To: <20220915015301.34744-4-epirat07@gmail.com> References: <20220915015301.34744-4-epirat07@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 6/7] avformat/avformat: Improve doxy style X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Marvin Scholz Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: sLddYT09dYZB 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);