From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pl1-f174.google.com (mail-pl1-f174.google.com [209.85.214.174]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9278E4A3E for ; Sun, 23 Nov 2025 11:28:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.174 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763897308; cv=none; b=AFA/WKRYuRdBCB9TqC6SmwpSElcIiTwId9TcF7Iu37t2iHvzdPGk9W50NgP9taoATH8GdExH+JEO4F+0puscw1t8uwXGoaYcmcgyDvGwAmD8xhr2NgvX/nsz7QesD19JIopnxS+JTRInDvaPvVJ2rPXdZ2zXqQvJF+9BiLaD/4o= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763897308; c=relaxed/simple; bh=kT57LczMOH07o602knbDM/aHRy0H+ccN//PzLKyZxzo=; h=Message-ID:Date:MIME-Version:To:Cc:References:Subject:From: In-Reply-To:Content-Type; b=TucMruImzZ8NyCT9JG1mRDZRqlGnK1DE7JLwJuGHYBGPx4kTQ0CWat3QnCos345n5GQO00uAYp3Z/c7RrymVzZ/q0+gCLo4mG4Gl9b40xPHRkxq7GDuTfJeB0kC75BbgzsROw1jtWpPhkWE1MAl0agrJEgV/EVvNA3dPJ2WF+oU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=K6xdleZw; arc=none smtp.client-ip=209.85.214.174 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="K6xdleZw" Received: by mail-pl1-f174.google.com with SMTP id d9443c01a7336-298145fe27eso54830155ad.1 for ; Sun, 23 Nov 2025 03:28:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1763897306; x=1764502106; darn=vger.kernel.org; h=content-transfer-encoding:in-reply-to:from:content-language:subject :references:cc:to:user-agent:mime-version:date:message-id:from:to:cc :subject:date:message-id:reply-to; bh=61tCAo806dIBQjZwytZtfz6gA3zKHHYqFzMOBDmk6es=; b=K6xdleZwCLf3CVslr10e1K8GdK3uqzFed/vJYVeK5YhHDxUqOrTz1CVqq5VYfu6HL6 PLKyHZHWXHtzbCGqAj/IwOe7CCO+jaePXhumcL/ua9PrN0u0jRzWyWya92xBiOlRNRuR +YXzyNJWTB7nQXuZ3UxVrnADe4cmfjdkaxmhhK53klYjDIoLVsWBs50qrKNOq4oiIsm5 zUiGMonpEP+Wkw1BPXcGU7TuZ3Jr0f3gPBjYnQArTipoG4WiQ9GVTZvxZqcx0rX8U+0j YvEZnt//0QWFB5QdphN/86ucJKlPB2IieY1XcRPQLT3zIiDMZ8Rph71pm6U6Lbzqrtg0 R0gA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1763897306; x=1764502106; h=content-transfer-encoding:in-reply-to:from:content-language:subject :references:cc:to:user-agent:mime-version:date:message-id:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=61tCAo806dIBQjZwytZtfz6gA3zKHHYqFzMOBDmk6es=; b=b2SidCSwM+EGg471n1OeEulsJCovs18/8oPsivTwnmeSQS7eN8lYp0noRUEa/D3Fl0 womBIkL46kPi+Vb8j9wIGovEylLqwcaTh1jAp2lKeFKbKxAy7PPTWM1EpOH5khk7M9OF dkOj2pEfI5XZyTV1PGeWV0RZhiSHMNVxtw88U//ouNUOA1OHas4HhoSl/rNtHPKV4E9r YX8R/KvH1FTQ4KpYdAn2N7hqwaFtS3nYoQqsCrhQrC2m5YEOMGERQhe2LXb41N/U4CSC B+M7/GY6V/YGgcqTkho7KnnINxRFRcXEydEmVNetVSIGgfr/XHeirZaCvKnRQtOcnSyb 0QDA== X-Forwarded-Encrypted: i=1; AJvYcCUpS1qEbIbpiRexkw6SGVAC4k4T9MWR3uVFV32UIpLyS043DLW5uApRe0qv7PUyHHJUgQBgXVoh0q2KgLQ=@vger.kernel.org X-Gm-Message-State: AOJu0Ywd2+AtdWvbugD5xaBX/dNyWrn2y/3k6oI9i2QgpjbKVpcaK/b2 zIAoCev/RzZVqaqCX6V40rCJiYk7vEDsIDWO71TIUJHRDEt2bsWPhhmu X-Gm-Gg: ASbGnctQl2EztM35ZqME/Ll1xg6HNlyBOhPAU/wXUB/UkPNMASozNEqTt/EkrJAfUzf AFMO39lrZLamKx6on64eZ65ywv8M4XYrCeNE6GKnNoaDjwmJMqk7GICqL/S+OL8JBCLyZzYR+Mf FDj5SEIKvMIzODMV6Jz6ikHG2xEwoLt4VrH1TO+TgKl/LnEo1pb8wzHKD8c67gHZMtlvlgfX4eZ 3bz3YOZFvL49dckbmkSu9cNsyJvZyuzkwLnGW0g2eOILIcsrzYw3tQvQMiCUGwdAEOYxG9I3zJn 1Yp6dPq70nimwsgcc3EMX5O5F3GGbk1Yk5b2cpMcLXmS/QzeJu88tzWvbreQDlSaSzO+Xgcj9Om NEdyTWn0aauHzSs3Dmfaso98QwrxSkbN1wVRA29bXedqHmgAPjvEMb4cro3Sdz8XQ2bTN5MDIwE ZdT2DUsz7A0pfL72FLnWLbY/E2jvEpMVqLsCjTkTqANmdeOpmU+D5OsMRy X-Google-Smtp-Source: AGHT+IFxWTJB63voHXky/YXI1TWJvYvO+sEuTf/VXA4Nb4YTLVhTU1RSL+X39WT0EdMWX3Np9XW0bA== X-Received: by 2002:a17:902:d592:b0:293:33b:a9b0 with SMTP id d9443c01a7336-29b6bf1a512mr87555105ad.32.1763897306035; Sun, 23 Nov 2025 03:28:26 -0800 (PST) Received: from [10.0.2.15] (KD106167137155.ppp-bb.dion.ne.jp. [106.167.137.155]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-29b5b13e720sm102905925ad.42.2025.11.23.03.28.24 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 23 Nov 2025 03:28:25 -0800 (PST) Message-ID: Date: Sun, 23 Nov 2025 20:28:23 +0900 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird To: mchehab+huawei@kernel.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, mchehab@kernel.org, rdunlap@infradead.org References: Subject: Re: [PATCH v4 0/5] kernel-doc: add support for documenting vars Content-Language: en-US From: Akira Yokosawa In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Hi Mauro, On Sat, 22 Nov 2025 13:37:54 +0100, Mauro Carvalho Chehab wrote: > Hi Jon, > > As suggested and discussed with Randy, this small series add support > for documenting variables using kernel-doc. > > - patch 1: add support for the new feature; > - patch 2: extends to support DEFINE_*; > - patch 3: document two media vars; > - patch 4: fix an issue on kernel-doc.rst markups and automarkup; > - patch 5: document it. > > On this version, I'm using "c:macro" to describe variables, as it > avoids Sphinx C domain to try parse the variable. This makes it more > flexible and easier to maintain in long term. In my test on top of current docs-next, I got two *new* warnings from "make cleandocs; make htmldocs": .../Documentation/driver-api/media/v4l2-common:8: ../include/media/v4l2-ioctl.h:665: WARNING: Inline emphasis start-string without end-string. [docutils] .../Documentation/driver-api/media/v4l2-common:8: ../include/media/v4l2-ioctl.h:678: WARNING: Inline emphasis start-string without end-string. [docutils] "scripts/kernel-doc -rst include/media/v4l2-ioctl.h" emits the following: .. c:macro:: v4l2_field_names => extern const char *v4l2_field_names[]; Helper array mapping V4L2_FIELD_* to strings. **Description** Specially when printing debug messages, it is interesting to output the field order at the V4L2 buffers. This array associates all possible values of field pix format from V4L2 API into a string. .. c:macro:: v4l2_type_names => extern const char *v4l2_type_names[]; Helper array mapping V4L2_BUF_TYPE_* to strings. **Description** When printing debug messages, it is interesting to output the V4L2 buffer type number with a name that represents its content. I think those declaration signatures need to be inline-literal. Thanks, Akira > > --- > > v4: > - document the new markup; > - fix an issue on kernel-doc.rst due to automarkup; > - add support for DEFINE_* macros > > Mauro Carvalho Chehab (5): > kernel-doc: add support for handling global variables > kernel-doc: add support to handle DEFINE_ variables > docs: media: v4l2-ioctl.h: document two global variables > docs: kernel-doc.rst: don't let automarkup mangle with consts > docs: kernel-doc.rst: document the new "var" kernel-doc markup > > Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++------ > include/media/v4l2-ioctl.h | 15 ++++++ > tools/lib/python/kdoc/kdoc_output.py | 46 ++++++++++++++++ > tools/lib/python/kdoc/kdoc_parser.py | 73 +++++++++++++++++++++++++- > 4 files changed, 166 insertions(+), 16 deletions(-) > > -- > 2.51.1