From patchwork Sun Sep 25 00:10:55 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 38238 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3b1c:b0:96:9ee8:5cfd with SMTP id c28csp1391266pzh; Sat, 24 Sep 2022 17:15:53 -0700 (PDT) X-Google-Smtp-Source: AMsMyM7FARbuyDCklLTZKIWyQDB0fnTHHLdaUnIPsFWF5nN0yRyMl0AbQOHI3PTOyr09xQCDfb+K X-Received: by 2002:a05:6402:1d48:b0:44e:c6cf:778 with SMTP id dz8-20020a0564021d4800b0044ec6cf0778mr15677088edb.421.1664064952840; Sat, 24 Sep 2022 17:15:52 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1664064952; cv=none; d=google.com; s=arc-20160816; b=wz8fPD/DzpbuiPyrSYDCWGHru+auxpVDTGelLbR+bx5dsNKd+9GhlMlZzNltOGiteY T7/efKTImNqCVaNyuVOCQkrg9ZCrdFfs8FAJVf3rxw6H5gELNk5lqU7hL+gObztKEc3C cLDebHyX67ra17aGXw4l9VOfpz5FU0n9Ak86B6NgUyYv7r7V3GAlUa/WMgf/7i21zruH rNYuXVI0yiQZesiMJfVSeHugSUIyB+7NaJ7CRV7mkh9fjYuuCi8yn4uYjmIelaXl39t4 EGcSzzas+wpZOeuB9/T9I8q6/8t+azFDQjpGmMivRKmbtY9L9niRkE0D7u/H20qkoupy yz7g== 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=7YFf1DUEsIjrMaU/69+VkLcU1O9dzty3m/nzk3zBoYA=; b=nH+O5pdDeS4qJJPmgBoMKEAkuwt9utSSrvo3Cnb05l6mT3hNF48U0oJo8dHO86hgZZ r0sVA/Tq6Q3jnpb0nA1Y2yOLvzvoN6iJABlECvggC6td1a0QRz/PODIvG05mPVSIVTi6 FH38pPcw6uhg7FpkU/03Z8N5ff1Pkm8Eld4OEhUL8dzPx8HBi9sw1ZRCM3spdRr+5e5Y 3DZwwYjD0jHbutgegQ6f4dUcm/pYy+XpTt6Yg08zi+LWmbRkBpZ0cBftKnV7Zq3PyGQt 00TvB3xkInc3Oex0hB6hQYbfduvnbTlzRp9PfsttBEFFYDHQlHVDKxi4aC7jsAJya495 WHrg== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=PNhHRz5Q; 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 tl2-20020a170907c30200b0078322e14382si1260340ejc.566.2022.09.24.17.15.51; Sat, 24 Sep 2022 17:15:52 -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=PNhHRz5Q; 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 A5F6368BC13; Sun, 25 Sep 2022 03:12:13 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ej1-f54.google.com (mail-ej1-f54.google.com [209.85.218.54]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D90E668BC05 for ; Sun, 25 Sep 2022 03:12:07 +0300 (EEST) Received: by mail-ej1-f54.google.com with SMTP id sb3so7406204ejb.9 for ; Sat, 24 Sep 2022 17:12:07 -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=B3/FeUavH9Lxz4bNe2t9yK26PDqGC0aTZS5fILsEeWk=; b=PNhHRz5QMiEX89tjV6XnSbjBPYqSpkYan5jeIWfNOFMDlCE0tenKX8RJBg+tlFMgSG jgTE9IMoqsNRhKEsb2BGT+2pfugAVs6lSNeFXifjKljhGjdvAtLs4Wm49oHDtN+lwb6u UXXeRyDEQebnDF0ZksyfUCdZVrIJZdNbsh3fANBV63iAC7gmscCpT1H9+h6UC8k5u9CV K01peKIZS0H83vAw2BjWggxVv1/abzSsECTEgkNBASulKd+xs7YFBKg4k0+tsC/+atfe yL15n2gMK4yneH1vy99dCm5JMIeWZ8XRlSLlJKbrS8Wp+21mIFyRMvcxmR7SY8NNE5jA u/JQ== 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=B3/FeUavH9Lxz4bNe2t9yK26PDqGC0aTZS5fILsEeWk=; b=cjLhBUTeb0dZI7AUTjGRWDTpYo480ENBymYh6xK/UYSAQHS+Pu/eoHTU093ZrLE5To 97rwRwv31DqhE6Zmz2Md9ccyKEQJg7RiwfwuDaypVPWZvIg7LW8rzAH1F/FktQWZB6Pc DaUWab0Dqvw+av1ygmazWx9nT7RUrUx9qvfQVIiGYaui6D4n/uWmt56NvotXi3BtbeU7 0xdhlbAagbA1nRhvCwVofGoiWxaSDjxGCVzpwJgketIAoHoYM/AfDXsr0bAM9tubFGaf TpOhKp76WZOQtlFzwM4YURMRIqhNEEeC+xDlbeAg9IRVgkd7X4l3o9IyA+XUUznN4oTQ CH5Q== X-Gm-Message-State: ACrzQf0jHgsjG+AKHGZFUxYOfxXyNaPaD7oWg3wzM4WuJ2XuRqDEm643 foL+sBMAneYRGTaBqo4nIhh6iGkuv90= X-Received: by 2002:a17:907:a052:b0:780:c4e4:1715 with SMTP id gz18-20020a170907a05200b00780c4e41715mr12743566ejc.55.1664064727454; Sat, 24 Sep 2022 17:12:07 -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 kz3-20020a17090777c300b007812ba2a360sm6208042ejc.149.2022.09.24.17.12.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 24 Sep 2022 17:12:07 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Sun, 25 Sep 2022 02:10:55 +0200 Message-Id: <20220925001121.37721-29-epirat07@gmail.com> X-Mailer: git-send-email 2.37.0 (Apple Git-136) In-Reply-To: <20220925001121.37721-1-epirat07@gmail.com> References: <20220922020400.46715-1-epirat07@gmail.com> <20220925001121.37721-1-epirat07@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v3 28/54] avutil/bprint: Improve doxy documentation 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: PbxJngaE8ap9 Declare proper group, add the file to that group, group the defines and document them. Use lists to represents lists of cases. --- libavutil/bprint.h | 78 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/libavutil/bprint.h b/libavutil/bprint.h index c09b1ac1e1..f27d30f723 100644 --- a/libavutil/bprint.h +++ b/libavutil/bprint.h @@ -18,6 +18,12 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/** + * @file + * @ingroup lavu_avbprint + * AVBPrint public header + */ + #ifndef AVUTIL_BPRINT_H #define AVUTIL_BPRINT_H @@ -26,6 +32,14 @@ #include "attributes.h" #include "avstring.h" +/** + * @defgroup lavu_avbprint AVBPrint + * @ingroup lavu_data + * + * A buffer to print data progressively + * @{ + */ + /** * Define a structure with extra padding to a fixed size * This helps ensuring binary compatibility with future versions. @@ -48,14 +62,14 @@ typedef struct name { \ * Small buffers are kept in the structure itself, and thus require no * memory allocation at all (unless the contents of the buffer is needed * after the structure goes out of scope). This is almost as lightweight as - * declaring a local "char buf[512]". + * declaring a local `char buf[512]`. * * The length of the string can go beyond the allocated size: the buffer is * then truncated, but the functions still keep account of the actual total * length. * - * In other words, buf->len can be greater than buf->size and records the - * total length of what would have been to the buffer if there had been + * In other words, AVBPrint.len can be greater than AVBPrint.size and records + * the total length of what would have been to the buffer if there had been * enough memory. * * Append operations do not need to be tested for failure: if a memory @@ -63,20 +77,17 @@ typedef struct name { \ * is still updated. This situation can be tested with * av_bprint_is_complete(). * - * The size_max field determines several possible behaviours: - * - * size_max = -1 (= UINT_MAX) or any large value will let the buffer be - * reallocated as necessary, with an amortized linear cost. - * - * size_max = 0 prevents writing anything to the buffer: only the total - * length is computed. The write operations can then possibly be repeated in - * a buffer with exactly the necessary size - * (using size_init = size_max = len + 1). - * - * size_max = 1 is automatically replaced by the exact size available in the - * structure itself, thus ensuring no dynamic memory allocation. The - * internal buffer is large enough to hold a reasonable paragraph of text, - * such as the current paragraph. + * The AVBPrint.size_max field determines several possible behaviours: + * - `size_max = -1` (= `UINT_MAX`) or any large value will let the buffer be + * reallocated as necessary, with an amortized linear cost. + * - `size_max = 0` prevents writing anything to the buffer: only the total + * length is computed. The write operations can then possibly be repeated in + * a buffer with exactly the necessary size + * (using `size_init = size_max = len + 1`). + * - `size_max = 1` is automatically replaced by the exact size available in the + * structure itself, thus ensuring no dynamic memory allocation. The + * internal buffer is large enough to hold a reasonable paragraph of text, + * such as the current paragraph. */ FF_PAD_STRUCTURE(AVBPrint, 1024, @@ -88,12 +99,31 @@ FF_PAD_STRUCTURE(AVBPrint, 1024, ) /** + * @name Max size special values * Convenience macros for special values for av_bprint_init() size_max * parameter. + * @{ + */ + +/** + * Buffer will be reallocated as necessary, with an amortized linear cost. */ #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1) +/** + * Use the exact size available in the AVBPrint structure itself. + * + * Thus ensuring no dynamic memory allocation. The internal buffer is large + * enough to hold a reasonable paragraph of text, such as the current paragraph. + */ #define AV_BPRINT_SIZE_AUTOMATIC 1 +/** + * Do not write anything to the buffer, only calculate the total length. + * + * The write operations can then possibly be repeated in a buffer with + * exactly the necessary size (using `size_init = size_max = AVBPrint.len + 1`). + */ #define AV_BPRINT_SIZE_COUNT_ONLY 0 +/** @} */ /** * Init a print buffer. @@ -101,12 +131,12 @@ FF_PAD_STRUCTURE(AVBPrint, 1024, * @param buf buffer to init * @param size_init initial size (including the final 0) * @param size_max maximum size; - * 0 means do not write anything, just count the length; - * 1 is replaced by the maximum value for automatic storage; - * any large value means that the internal buffer will be - * reallocated as needed up to that limit; -1 is converted to - * UINT_MAX, the largest limit possible. - * Check also AV_BPRINT_SIZE_* macros. + * - `0` means do not write anything, just count the length + * - `1` is replaced by the maximum value for automatic storage + * any large value means that the internal buffer will be + * reallocated as needed up to that limit + * - `-1` is converted to `UINT_MAX`, the largest limit possible. + * Check also `AV_BPRINT_SIZE_*` macros. */ void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max); @@ -216,4 +246,6 @@ int av_bprint_finalize(AVBPrint *buf, char **ret_str); void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars, enum AVEscapeMode mode, int flags); +/** @} */ + #endif /* AVUTIL_BPRINT_H */