From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id DE721447C9 for ; Sun, 25 Sep 2022 00:15:49 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 8003068BBCC; Sun, 25 Sep 2022 03:12:13 +0300 (EEST) 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-Google-Smtp-Source: AMsMyM72eqX2g18F/qfPn8FDsg04wHPKHPGed7wbTolfgtedv6xPgLJuf4Wqmvik7k0stuI3L3WrBQ== 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 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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 */ -- 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".