From patchwork Sat Sep 28 14:28:26 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 51912 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:d8ca:0:b0:48e:c0f8:d0de with SMTP id dy10csp1014220vqb; Sat, 28 Sep 2024 07:28:58 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUxMHOsrIQitIMxCZI7yNwd6QGTh3gJ0bn70E1posfl41Wg+zc6ybL7bdvDwonMCYqP77FwelWBvcff8AijZGXK@gmail.com X-Google-Smtp-Source: AGHT+IFVj4WLd7V9dVLaEmyxGF/pBo4BKlH1sWwxi0QgusUx4ozjMOEySVzUSu0a1sm87Uub9QiH X-Received: by 2002:a2e:be12:0:b0:2f7:a759:72a7 with SMTP id 38308e7fff4ca-2f9d3e561dfmr38081051fa.22.1727533738197; Sat, 28 Sep 2024 07:28:58 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1727533738; cv=none; d=google.com; s=arc-20240605; b=EvOrpG0Pt1seNwILpJy7lYYHIyN6Qy4gfV+/cC4X6iZx4OiNYx+JyYpZVw+KGSRS6+ +ESka3YNesXfyAh/PnNP/o9VyTlonra3B8ZUteHpz4dvHzq98Kbe5rli39WteHxXu8Sf M45PZ0f465QBmigrm5SHTVSX73ZfSTprsht4MPSOFCOXZTlIGjBlsNlbYIzqnQSugy5J v9IwS07ww2TPbL7+DcyhvwJQk33mfYsE/ysiVe9DCbBPiFRmErZlmahgoDTp97oAGOEE 9h1MhgW9TyRfpuGyhOxsbkU0Dpw3BUnAz3CGvsKiFXwARRgeKAR1nhltv/tYfsrwqNv/ Zqwg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:message-id:date:to:from :dkim-signature:delivered-to; bh=61N4q23iuMDPkWrkf7Y+a3jtlfO3wYv1T9q0dfJ2fU0=; fh=YOA8vD9MJZuwZ71F/05pj6KdCjf6jQRmzLS+CATXUQk=; b=BwEYe4KDe3HrxGZ4Txm+GCAK8i6Ae9XrdRdJpWlbHD2OHDem0GsEQr3elj66guBylY OwTCQzLmvKjJP3KnOi1ddhXtNLT/r2773BQVI9fNclxfuCnf0/64g8+M1+Kh53ma3DbU ox9UyXIjwvHXWRbvNOaK/b2mC8MMfyUVL9XW0H3tLM2cW0b+ljdi8Y+yLylHIrHfjBkB c/sqMzVSssWUvZt1ezZpyUpsyJsBF9DC5awekaJamg9lue6XqFqzKA84BJXDzistpg7e Zlo1eogRkPsgrVy1PMIwLKA5LUG8ofh9rP00Yaoz/WzLJEm6zyLYG5iJwEKTU1g/0Fpi 7RUg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@khirnov.net header.s=mail header.b=QDfUA9vW; 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 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id 38308e7fff4ca-2f9d45d6f76si13987801fa.158.2024.09.28.07.28.57; Sat, 28 Sep 2024 07:28:58 -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=@khirnov.net header.s=mail header.b=QDfUA9vW; 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 Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 4ABFE68D99C; Sat, 28 Sep 2024 17:28:43 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail1.khirnov.net (quelana.khirnov.net [94.230.150.81]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 064AD68D8D8 for ; Sat, 28 Sep 2024 17:28:35 +0300 (EEST) Authentication-Results: mail1.khirnov.net; dkim=pass (2048-bit key; unprotected) header.d=khirnov.net header.i=@khirnov.net header.a=rsa-sha256 header.s=mail header.b=QDfUA9vW; dkim-atps=neutral Received: from localhost (mail1.khirnov.net [IPv6:::1]) by mail1.khirnov.net (Postfix) with ESMTP id BA1B04E0B for ; Sat, 28 Sep 2024 16:28:33 +0200 (CEST) Received: from mail1.khirnov.net ([IPv6:::1]) by localhost (mail1.khirnov.net [IPv6:::1]) (amavis, port 10024) with ESMTP id BNAXnvdx3Kqh for ; Sat, 28 Sep 2024 16:28:32 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=khirnov.net; s=mail; t=1727533712; bh=nocfs6VNYgpU+2IK/pFB/sBgjlRnJNqsAKaxcCWXDwI=; h=From:To:Subject:Date:From; b=QDfUA9vWd+3xeMoawiqShmO3Wp56W+QInLQ+VgX5QqcSxuis8UymVLnWQCFhrCnp/ 7Qx6FvKOpvn2Npmzta9Il3H1ST91wLU8k/YqLnjqHuPHOf+DJTKEqcDk4xVkl0KwhJ gIfcbZfNjCTF531PjkkmzSFYrlV7wMQzxsD41DAD5deiImeRSP6LsSdNsuqrUmQ8jj rRcJQFhgJDtBu/V98+rdlVZL50YNewBNRSI5RFJQbjC67HbwEbf7FWkhiA1AomvVBP ZGeo3Is+NkfYlZRRBxMXTVxnxSb+VKN8Ig+Q+WOTEEgLG8gxq5H7DpuJMCO6pvcGSf RYSjWaypvnSaw== Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail1.khirnov.net (Postfix) with ESMTPS id 97C694D9D for ; Sat, 28 Sep 2024 16:28:32 +0200 (CEST) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id 6D8B93A0229 for ; Sat, 28 Sep 2024 16:28:32 +0200 (CEST) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Sat, 28 Sep 2024 16:28:26 +0200 Message-ID: <20240928142830.961-1-anton@khirnov.net> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/5] lavu/class: improve AVClass doxy 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: aC0sR7U9LXFq --- libavutil/log.h | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..c6b47cc054 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -77,7 +77,9 @@ typedef struct AVClass { const char* (*item_name)(void* ctx); /** - * a pointer to the first option specified in the class if any or NULL + * An array of options for the structure or NULL. + * When non-NULL, the array must be terminated by an option with a NULL + * name. * * @see av_set_default_options() */ @@ -85,43 +87,50 @@ typedef struct AVClass { /** * LIBAVUTIL_VERSION with which this structure was created. - * This is used to allow fields to be added without requiring major - * version bumps everywhere. + * This is used to allow fields to be added to AVClass without requiring + * major version bumps everywhere. */ int version; /** - * Offset in the structure where log_level_offset is stored. - * 0 means there is no such variable + * Offset in the structure where the log level offset is stored. The log + * level offset is added to the log level for logging with this object as + * the context. + * + * 0 means there is no such variable. */ int log_level_offset_offset; /** * Offset in the structure where a pointer to the parent context for * logging is stored. For example a decoder could pass its AVCodecContext - * to eval as such a parent context, which an av_log() implementation + * to eval as such a parent context, which an ::av_log() implementation * could then leverage to display the parent context. - * The offset can be NULL. + * + * When the pointer is NULL, or this offset is zero, the object is assumed + * to have no parent. */ int parent_log_context_offset; /** - * Category used for visualization (like color) - * This is only set if the category is equal for all objects using this class. - * available since version (51 << 16 | 56 << 8 | 100) + * Category used for visualization (like color). + * + * Only used when ::get_category() is NULL. Use this field when all + * instances of this class have the same category, use ::get_category() + * otherwise. */ AVClassCategory category; /** - * Callback to return the category. - * available since version (51 << 16 | 59 << 8 | 100) + * Callback to return the instance category. Use this callback when + * different instances of this class may have different categories, + * ::category otherwise. */ AVClassCategory (*get_category)(void* ctx); /** * Callback to return the supported/allowed ranges. - * available since version (52.12) */ int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags); @@ -139,9 +148,11 @@ typedef struct AVClass { * @return AVClass for the next AVOptions-enabled child or NULL if there are * no more such children. * - * @note The difference between child_next and this is that child_next - * iterates over _already existing_ objects, while child_class_iterate - * iterates over _all possible_ children. + * @note The difference between ::child_next() and ::child_class_iterate() + * is that ::child_next() iterates over _actual_ children of an + * _existing_ object instance, while ::child_class_iterate() iterates + * over the classes of all _potential_ children of any possible + * instance of this class. */ const struct AVClass* (*child_class_iterate)(void **iter); } AVClass;