From patchwork Thu Sep 22 02:03:59 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 38143 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3b1c:b0:96:9ee8:5cfd with SMTP id c28csp657pzh; Wed, 21 Sep 2022 19:05:07 -0700 (PDT) X-Google-Smtp-Source: AMsMyM6kAQ4qhcidFbrOtQr+Oh3tvmPVUt4QeAGFWYedZQ6JBIVEMEbZ/5z44WOIVCooT+2gyBAh X-Received: by 2002:a17:906:6a0b:b0:77d:2f20:69db with SMTP id qw11-20020a1709066a0b00b0077d2f2069dbmr849168ejc.572.1663812306857; Wed, 21 Sep 2022 19:05:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1663812306; cv=none; d=google.com; s=arc-20160816; b=cbWNoIjNPG1UdDYnIXygN4wwIR/ZLQWaP9D/6+lrq5P6xAgw+sEjmnKPZSdN5GJkWR GSiL1rBqDJhmpN+C+kKZQT5fYD9G/zlcBFmGTTNyzVgjCsV4zD1zUArCKHKweC3YrYxr jbdl5A21udRlWjn6FDoZYuu9NV0mGuwmC50oRFoAbpD1CxKKxscBZaX5Kg2q9WrEy3wV yGEHkM7dHDztGRAAs85lc8mRN3q9n1W5sX8j3PTJ+dt0fKNDlV/cFy5XfNlPmZ65+94+ 8gDaaVT7/2c0/ZvGChryzQe21kTbiBFGe5Ou4PRxUDWlKxKaUOg+Mt4eH4MoqRk6XTGl rjOg== 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=C2EzBpH2Cfd4jE1iHMMiZs8Ez5Z5YKpYWyduCUwVQeM9XGwXLiWPTX690woN9qoDgE a1q6H+VQj07MbVwgo8gUWzLcWVo5b5uA/DIo1L6XVfOU2j7QJWV740bZctaysXiyTOPQ +m+c26rssxeqkR2wG8IHJq7yIB6GAyxZ9mWZHIitAKV3RpjyBSsOeN/Jx1TlFTnP7oWK piGQEGf4GurLm1up83aPCUYkS5wTdqs6mQn6X6DLcmjLA9C4v0s5MZ3uODkUBI/XkwMW Py/SdgU5yzAhIPvO2QjHGWTjPbt1TbA1U0NJq4Jk8BM82Ol3m153pjLWnoNiSILexn+2 oQDA== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=eh8ueiJf; 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 o8-20020a170906974800b0073dda1430b9si4483833ejy.403.2022.09.21.19.04.59; Wed, 21 Sep 2022 19:05:06 -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=eh8ueiJf; 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 74F6F68BBA3; Thu, 22 Sep 2022 05:04:17 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ej1-f52.google.com (mail-ej1-f52.google.com [209.85.218.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id E08B768B1CE for ; Thu, 22 Sep 2022 05:04:08 +0300 (EEST) Received: by mail-ej1-f52.google.com with SMTP id lh5so17827880ejb.10 for ; Wed, 21 Sep 2022 19:04:08 -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=eh8ueiJflSUDHGuG/GgHskH4lc8yOsFNWKMpIOntRKFwOxdehOgPlyecmBZprrBKUn zDslY/SuLZDwB4EoI6XutVuOvM9F2nDbW7/oLf1W0ueWopdvjKjaeOuvwBLQacCDpg8h rprS35b8aAwKqb5HVo9y6Cqc//+CKE/MNZl43pbtUqfzWSTwwTVeRQos/RUf+GPK8bjo hoH7LGOv/J/L0VPjrKDilrD+o9or2SKcobY7mAegG11aoew4dhaCwhDqy92X7HT3Bj3o /wPMjNqZR3GmCmYHoJGY8+y/xish1ufsdEEOUoVWyUMsCU5ahHGUxcbLr9JD5mvA3cxS f1Pw== 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=VvxVy6ek1vLLjTA6UrdwYaDKcu4Xa/oETru7IBqB+cwazPPHBHXpkqwoGwMe3nyCDp dwjosn/c/wQWZoRdv9L+x5EU7YpD010yNzN3CyUdHWo9iSQPxzCVs+82YXUcakWhv0pQ /4gtAIVv0qh99tV6zYM1d8h4lev4b8AdY5oA9QRaH87ivMY/jeauscGpMlh+zD8K5bPe FwDu/E0hzBO8yv80hgZ7TkJJl0JDsWx6GCXmnbqQEfNoV6U9K1xCUgOrGK73+wd9QCm6 Bedeb3C/a282tJoPAFfjxFRxp49PBBHQlZuCzwJd8ubJZyai7My7yGH2IVfT7oJLrYdd 9jiQ== X-Gm-Message-State: ACrzQf1hxic7+ablAsECsapqy9D7WNOMEGsd6afU1io5e/uqNu6Eajkq YfLYqjc146WyvTO+fEkXkpvThJcz/KQ= X-Received: by 2002:a17:906:dac8:b0:741:545b:796a with SMTP id xi8-20020a170906dac800b00741545b796amr891706ejb.240.1663812248226; Wed, 21 Sep 2022 19:04:08 -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 b10-20020aa7df8a000000b0044e01e2533asm2836847edy.43.2022.09.21.19.04.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 21 Sep 2022 19:04:07 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Thu, 22 Sep 2022 04:03:59 +0200 Message-Id: <20220922020400.46715-6-epirat07@gmail.com> X-Mailer: git-send-email 2.37.0 (Apple Git-136) In-Reply-To: <20220922020400.46715-1-epirat07@gmail.com> References: <20220922020400.46715-1-epirat07@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v2 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: +osts92BLFk3 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);