From nobody Tue Dec 2 01:03:04 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 419432F7465; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; cv=none; b=h7rBR2aJmbqnX3/VJxcSr6qADkq4+E4X9L2tU34M/dt9CtrlweEuN17jZwMn6o19JlNOglU4JO1dENer+Ldku8j3SmlFvzon2o3BoEdNlG8EkSCT0zubU/zfPiozroJTQnxfGcobFxV6y02KMle0gX2J7N4k94lcPlPpk66Lswo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; c=relaxed/simple; bh=3mMj2/bpTFkS1JYhOQCrsyMcgLS2GZpq30GUkfbjkfo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=M8GmIFoAAp6sxsJc0ooumrf4FrOZboGmh1eLMdJ/SN+QIqTv64C98FUt3jvq0QSvBrGEmvORDz91dNwWOdLO+XZYtgKAfoeOmHFyuxy+Sqn6TeYbp6jcjRMXyr9zkMRbFtXcbLhd/4YQLNC9li+2zj9awmSO8ucEzMIbAmS0IuE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sRjkr/9y; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="sRjkr/9y" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D9983C4CEF1; Mon, 24 Nov 2025 09:57:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1763978275; bh=3mMj2/bpTFkS1JYhOQCrsyMcgLS2GZpq30GUkfbjkfo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sRjkr/9y/S3J3nn0oRA1BYaYl+/9FpdqkM5DZvharGOT2C3VGHgsC1TZJWXR5y8Qo T+zueOrYe4A6gph7oFdJmBUZPTiFYZrx5hzHEIJfFtjG/t+EqhdUMeQa4aai/bc2SO IYYelnnwYAtvjH933HONP8CNYuu0WK0W9dvON4LutrNWpj4QqPDK/6HODFGyhguzjM c4A0pQfeCKMW1LHSc5UDhyOdmECMC7yXz8zIQanbm+HMxyrfkEC0Qh7fMlfZd0sT0f lHCeUtVH0BGUEMLBpZOKC3CKS12K6AFvHviYdqlKnhjuHUeTEVFX30+XFU/tZ+nDQr 4paur02+oYAHg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vNTKU-000000013c0-0WII; Mon, 24 Nov 2025 10:57:54 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Randy Dunlap" , linux-kernel@vger.kernel.org Subject: [PATCH v5 1/5] kernel-doc: add support for handling global variables Date: Mon, 24 Nov 2025 10:57:42 +0100 Message-ID: X-Mailer: git-send-email 2.51.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI. Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us. Add support for it. Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c0= 9@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 Suggested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- tools/lib/python/kdoc/kdoc_output.py | 47 +++++++++++++++++++++++ tools/lib/python/kdoc/kdoc_parser.py | 56 +++++++++++++++++++++++++++- 2 files changed, 102 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 14378953301b..8d811c2afaab 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -199,6 +199,10 @@ class OutputFormat: self.out_enum(fname, name, args) return self.data =20 + if dtype =3D=3D "var": + self.out_var(fname, name, args) + return self.data + if dtype =3D=3D "typedef": self.out_typedef(fname, name, args) return self.data @@ -227,6 +231,9 @@ class OutputFormat: def out_enum(self, fname, name, args): """Outputs an enum""" =20 + def out_var(self, fname, name, args): + """Outputs a variable""" + def out_typedef(self, fname, name, args): """Outputs a typedef""" =20 @@ -472,6 +479,25 @@ class RestFormat(OutputFormat): self.lineprefix =3D oldprefix self.out_section(args) =20 + def out_var(self, fname, name, args): + oldprefix =3D self.lineprefix + ln =3D args.declaration_start_line + full_proto =3D args.other_stuff["full_proto"] + + self.lineprefix =3D " " + + self.data +=3D f"\n\n.. c:macro:: {name}\n\n{self.lineprefix}{full= _proto}\n\n" + + self.print_lineno(ln) + self.output_highlight(args.get('purpose', '')) + self.data +=3D "\n" + + if args.other_stuff["default_val"]: + self.data +=3D f'{self.lineprefix}**Initialization**\n\n' + self.output_highlight(f'default: ``{args.other_stuff["default_= val"]}``') + + self.out_section(args) + def out_typedef(self, fname, name, args): =20 oldprefix =3D self.lineprefix @@ -773,6 +799,27 @@ class ManFormat(OutputFormat): self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(text) =20 + def out_var(self, fname, name, args): + out_name =3D self.arg_name(args, name) + prototype =3D args.other_stuff["var_type"] + full_proto =3D args.other_stuff["full_proto"] + + self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + + self.data +=3D ".SH NAME\n" + self.data +=3D f"{prototype} \\- {args['purpose']}\n" + + self.data +=3D ".SH SYNOPSIS\n" + self.data +=3D f"{full_proto}\n" + + if args.other_stuff["default_val"]: + self.data +=3D f'.SH "Initialization"' + "\n" + self.output_highlight(f'default: {args.other_stuff["default_va= l"]}') + + for section, text in args.sections.items(): + self.data +=3D f'.SH "{section}"' + "\n" + self.output_highlight(text) + def out_typedef(self, fname, name, args): module =3D self.modulename purpose =3D args.get('purpose') diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index c0cc714d4d6f..edb0fb5330e0 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -64,7 +64,7 @@ type_param =3D KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)= ", cache=3DFalse) # Tests for the beginning of a kerneldoc block in its various forms. # doc_block =3D doc_com + KernRe(r'DOC:\s*(.*)?', cache=3DFalse) -doc_begin_data =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*= )", cache =3D False) +doc_begin_data =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|var)\b\s*= (\w*)", cache =3D False) doc_begin_func =3D KernRe(str(doc_com) + # initial " * ' r"(?:\w+\s*\*\s*)?" + # type (not captured) r'(?:define\s+)?' + # possible "define" (not cap= tured) @@ -924,6 +924,58 @@ class KernelDoc: self.output_declaration('enum', declaration_name, purpose=3Dself.entry.declaration_purpose) =20 + def dump_var(self, ln, proto): + """ + Store variables that are part of kAPI. + """ + VAR_ATTRIBS =3D [ + "extern", + ] + OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" + + sub_prefixes =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + (KernRe(r"=3D.*"), ""), + ] + + # + # Store the full prototype before modifying it + # + full_proto =3D proto + + # + # Drop comments and macros to have a pure C prototype + # + for search, sub in sub_prefixes: + proto =3D search.sub(sub, proto) + + proto =3D proto.rstrip() + + # + # Variable name is at the end of the declaration + # + + r=3D KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\= []*\s*(=3D.*)?") + if not r.match(proto): + self.emit_msg(ln,f"{proto}: can't parse variable") + return + + var_type =3D r.group(0) + declaration_name =3D r.group(1) + default_val =3D r.group(2) + if default_val: + default_val =3D default_val.lstrip("=3D").strip() + + self.output_declaration("var", declaration_name, + full_proto=3Dfull_proto, + var_type=3Dvar_type, + default_val=3Ddefault_val, + purpose=3Dself.entry.declaration_purpose) + def dump_declaration(self, ln, prototype): """ Stores a data declaration inside self.entries array. @@ -935,6 +987,8 @@ class KernelDoc: self.dump_typedef(ln, prototype) elif self.entry.decl_type in ["union", "struct"]: self.dump_struct(ln, prototype) + elif self.entry.decl_type =3D=3D "var": + self.dump_var(ln, prototype) else: # This would be a bug self.emit_message(ln, f'Unknown declaration type: {self.entry.= decl_type}') --=20 2.51.1 From nobody Tue Dec 2 01:03:04 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 419C72F7468; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; cv=none; b=gw66tsHKjXZTPyn99/AFEP5q1eqIitdice62uF1sUhA1FQC4Nz9NsrUWuZmM0wwvwN/2KWA4F3gIfEok5hddAIckK/2R8LM8fgZau8Wvei2D2eK7OkRU1q8k11Sxv/Y916oNRGiEGmuqk3NJ0sNg7MMcKW2BZJIRVYtqYtdb5Zk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; c=relaxed/simple; bh=9Ismxj297GqUp52pxp1UAgRMzcZZT3Gw6Sjv2/ZSBZI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=fbLFd87l4xOyS4yrkXX2IrOf0zpFwbi+wtkI3pXn3V23zyY92V3uTcxAP4NqbSXhiB4H+oyG3GbqZLstOTk4lMqEvN5/ecUwX4d3zhJgEWafIJ8oyKqq/g94NI2mmOzOmwldmg/G8LzuoPzWohY2HRSKkRrlz0JWUegw+bQ8UdE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pkKUnHB3; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="pkKUnHB3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F0AE0C19423; Mon, 24 Nov 2025 09:57:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1763978276; bh=9Ismxj297GqUp52pxp1UAgRMzcZZT3Gw6Sjv2/ZSBZI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pkKUnHB3iB7dcNti78RUUdH0cEwOBdpcp1d++SEF+jQSaaXnggv/nEfd4UXiWHqUX p0o5OqVHoj5VCSj73PwrnEt8Bu36B9I0b5SvpmxDDecZvhKahHCFGYvG9ongFzbn35 ENzkxZGq2cDc2PAIG7LcYheot0E8CtRn06A3njEljRyaDi+cOgZvvQwOu3bET63J6e fQ+NCPR7pK7qA5V8Pi3CchA4tw8L2sMQx/GVYQtQPxbWaTQ2rTuLbTqIfvfS82IRuQ sJNvxeqBFMFJ34hxWKzevVyQTVPj/FH/+ic8Lmk2UIbELnpNqO5M1BNs28MnQSbUCy IM7EKJYolpOGg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vNTKU-000000013c4-0dRz; Mon, 24 Nov 2025 10:57:54 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Randy Dunlap" , linux-kernel@vger.kernel.org Subject: [PATCH v5 2/5] kernel-doc: add support to handle DEFINE_ variables Date: Mon, 24 Nov 2025 10:57:43 +0100 Message-ID: X-Mailer: git-send-email 2.51.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Improve the parser and output plugin to work with macros, adding support for the common pattern of using DEFINE_* to create variables. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 5 ++--- tools/lib/python/kdoc/kdoc_parser.py | 25 +++++++++++++++++++++---- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 8d811c2afaab..9f09c763a009 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -486,7 +486,7 @@ class RestFormat(OutputFormat): =20 self.lineprefix =3D " " =20 - self.data +=3D f"\n\n.. c:macro:: {name}\n\n{self.lineprefix}{full= _proto}\n\n" + self.data +=3D f"\n\n.. c:macro:: {name}\n\n{self.lineprefix}``{fu= ll_proto}``\n\n" =20 self.print_lineno(ln) self.output_highlight(args.get('purpose', '')) @@ -801,13 +801,12 @@ class ManFormat(OutputFormat): =20 def out_var(self, fname, name, args): out_name =3D self.arg_name(args, name) - prototype =3D args.other_stuff["var_type"] full_proto =3D args.other_stuff["full_proto"] =20 self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" - self.data +=3D f"{prototype} \\- {args['purpose']}\n" + self.data +=3D f"{name} \\- {args['purpose']}\n" =20 self.data +=3D ".SH SYNOPSIS\n" self.data +=3D f"{full_proto}\n" diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index edb0fb5330e0..a3cd1bb0c8e7 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -946,12 +946,27 @@ class KernelDoc: # Store the full prototype before modifying it # full_proto =3D proto + declaration_name =3D None + + # + # Handle macro definitions + # + macro_prefixes =3D [ + KernRe(r"DEFINE_[\w_]+\s*\(([\w_]+)\)"), + ] + + for r in macro_prefixes: + match =3D r.search(proto) + if match: + declaration_name =3D match.group(1) + break =20 # # Drop comments and macros to have a pure C prototype # - for search, sub in sub_prefixes: - proto =3D search.sub(sub, proto) + if not declaration_name: + for r, sub in sub_prefixes: + proto =3D r.sub(sub, proto) =20 proto =3D proto.rstrip() =20 @@ -965,14 +980,16 @@ class KernelDoc: return =20 var_type =3D r.group(0) - declaration_name =3D r.group(1) + + if not declaration_name: + declaration_name =3D r.group(1) + default_val =3D r.group(2) if default_val: default_val =3D default_val.lstrip("=3D").strip() =20 self.output_declaration("var", declaration_name, full_proto=3Dfull_proto, - var_type=3Dvar_type, default_val=3Ddefault_val, purpose=3Dself.entry.declaration_purpose) =20 --=20 2.51.1 From nobody Tue Dec 2 01:03:04 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 418442F745B; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; cv=none; b=nggaabpP96PB+KHxgYP9YrDRdE/sdsf+NcUtbp4ptmi6aQGhwIiKeIFkIz1C8bZ7Ggi/sVwczuwKAgCWDierQjNC+3I4XMCNcfomicDGBqfjrRF8JGWl0kf/38CceXG6utz0vO8uDqnmYjg25y/t4gCar4LmxXXFq/ayj2UTaTU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; c=relaxed/simple; bh=Ik0bwiscH39XA81eEpRwbrxBFIfeeaIoMwR5sWLhRX0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BEYgnnhBCMCxvlUElnZUxSBqd+IwEczsqeDHMZj3aFIGz9AqWVxKnJ3KpOecsqF43VuQ0NS0rqslg+jaOdppB0d3y1wNCfJSF7ZzMHJgbMrEjp7FxoGYicAW6j3VeFKtG6nd7uaz6Z4Yj4OTK8R8TCZkVI9lQq8CYFCZBuPloP0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=HCn1FAer; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="HCn1FAer" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EAA92C19421; Mon, 24 Nov 2025 09:57:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1763978276; bh=Ik0bwiscH39XA81eEpRwbrxBFIfeeaIoMwR5sWLhRX0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HCn1FAeracqS4C5RHH3gtIyy1o4+mdfUbxdO5ZGnc8l6dh9Y3LGt8kBTnHoFH51fF qPhDuAsobF8jmLaz9Ove1jV/2HyPEb722xX6psuwr/j+Ap3du3JQmvuz08f2s5PLC5 TVzBN4Sy5o8K9HFCGhHJ7lw+GDgpLky33+sV2Y/xGfqjdqXp7pAUNW4P7jvoGbE7v6 KTZb0nPbFgxH60KjiH0pPdqMKvX8wq7rmCavaUdT7A41n1dhkkN5kEru6RLNhP4ei8 E2vTR7mDr0iMoWyWcTChcqw025mvusNdDvsjnwM6AjqjEjoXFXnijN5NaJu6efmcSr 4DuL+z2/+IJrA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vNTKU-000000013c8-0kV4; Mon, 24 Nov 2025 10:57:54 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Randy Dunlap" , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org Subject: [PATCH v5 3/5] docs: media: v4l2-ioctl.h: document two global variables Date: Mon, 24 Nov 2025 10:57:44 +0100 Message-ID: <8a834e98624795aa02070752d3d49a9ba40a86e7.1763978209.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" The media kAPI has two global variables at v4l2-ioctl.h. Document them. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- include/media/v4l2-ioctl.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h index 6f7a58350441..54c83b18d555 100644 --- a/include/media/v4l2-ioctl.h +++ b/include/media/v4l2-ioctl.h @@ -663,7 +663,22 @@ void v4l_printk_ioctl(const char *prefix, unsigned int= cmd); struct video_device; =20 /* names for fancy debug output */ + +/** + * var v4l2_field_names - Helper array mapping ``V4L2_FIELD_*`` to strings. + * + * 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. + */ extern const char *v4l2_field_names[]; + +/** + * var v4l2_type_names - Helper array mapping ``V4L2_BUF_TYPE_*`` to strin= gs. + * + * When printing debug messages, it is interesting to output the V4L2 buff= er + * type number with a name that represents its content. + */ extern const char *v4l2_type_names[]; =20 #ifdef CONFIG_COMPAT --=20 2.51.1 From nobody Tue Dec 2 01:03:04 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 418C42F7462; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; cv=none; b=ikHAyKTwS6FfDiVdQ5JZ/dyudRKQbfvf778h6VfPtpkz5zZte7yx39K4MYks3d3VVTJ0DT3mmEqWIUAIe8Kuo68RP0/Bils2X+g2ZPmJGI1WlqvjYyCi7Hp15SQH1RGmAd0J4MAQ4HvH5b9LmBJwJzACyG/CMOd5wnwHA1fRJn0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; c=relaxed/simple; bh=G398QL1RFc7oMj9o4VEOCqV1JI6qx7V76XAbDiL7j8o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sEkxsdw4YCcTcrmV3u//4DQ6nhM58Zfj6RHtXo6QbPrn5H+t3q8P5Oq5DMbgPb+59JZFpRTxexUzn1BrdQuqQCIMKo+e4UaHRnNnbanvuKRwfkeNLIoNEATvtq5OuEHPO4DFh9o254ZM5MsTIuiBw/1f8WQP3wFUSnIRKAMVzbY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dH1yXeHw; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="dH1yXeHw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EECEAC116D0; Mon, 24 Nov 2025 09:57:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1763978276; bh=G398QL1RFc7oMj9o4VEOCqV1JI6qx7V76XAbDiL7j8o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dH1yXeHwCQHXnkl5FmSFjJoF8hf9KVUb1hs3vo9qUuF0mlN4w37L+T8/pWKpX6oit +uKbjsiuS2MxIt2vtsx75Tb8d8Pc3RzdHShs7r4SAzOFGkXge+3bQBLm3K7lI0yJ/Z mzfvSccl4OLRkOT6kZ5j0/sAG7CXRQxl8Wj1EY3y7JjmQUOICRuWInfyQnAxhBgesP oc4+fttanMf0dfPkoUUeMsWVuOk19PAKC72mgzX93wugskUz56eawhei+Oj94K1zq4 0T7xsAc1IVzl0B7RulPe6DOsNvJ1SkWDlv2k71xsbsxwWHhX17AcAzHh26G31d2fbT 41c1TgQ7iHcAw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vNTKU-000000013cC-0reY; Mon, 24 Nov 2025 10:57:54 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Randy Dunlap" , linux-kernel@vger.kernel.org Subject: [PATCH v5 4/5] docs: kernel-doc.rst: don't let automarkup mangle with consts Date: Mon, 24 Nov 2025 10:57:45 +0100 Message-ID: <03b92bb6a6a482d4e365f2da9011dda9a82a7249.1763978209.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" This document contains several words that tricks automarkup. Ensure that all of them will be inside a ``const`` markup, avoiding automarkup to touch them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Randy Dunlap --- Documentation/doc-guide/kernel-doc.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-gui= de/kernel-doc.rst index fd89a6d56ea9..2e18a810f98b 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -174,7 +174,8 @@ named ``Return`` (or ``Returns``). Structure, union, and enumeration documentation ----------------------------------------------- =20 -The general format of a struct, union, and enum kernel-doc comment is:: +The general format of a ``struct``, ``union``, and ``enum`` kernel-doc +comment is:: =20 /** * struct struct_name - Brief description. @@ -187,8 +188,8 @@ The general format of a struct, union, and enum kernel-= doc comment is:: */ =20 You can replace the ``struct`` in the above example with ``union`` or -``enum`` to describe unions or enums. ``member`` is used to mean struct -and union member names as well as enumerations in an enum. +``enum`` to describe unions or enums. ``member`` is used to mean ``struct= `` +and ``union`` member names as well as enumerations in an ``enum``. =20 The brief description following the structure name may span multiple lines, and ends with a member description, a blank comment line, or the @@ -201,7 +202,7 @@ Members of structs, unions and enums should be document= ed the same way as function parameters; they immediately succeed the short description and may be multi-line. =20 -Inside a struct or union description, you can use the ``private:`` and +Inside a ``struct`` or ``union`` description, you can use the ``private:``= and ``public:`` comment tags. Structure fields that are inside a ``private:`` area are not listed in the generated output documentation. =20 @@ -273,11 +274,11 @@ It is possible to document nested structs and unions,= like:: =20 .. note:: =20 - #) When documenting nested structs or unions, if the struct/union ``foo= `` - is named, the member ``bar`` inside it should be documented as + #) When documenting nested structs or unions, if the ``struct``/``union= `` + ``foo`` is named, the member ``bar`` inside it should be documented = as ``@foo.bar:`` - #) When the nested struct/union is anonymous, the member ``bar`` in it - should be documented as ``@bar:`` + #) When the nested ``struct``/``union`` is anonymous, the member ``bar`= ` in + it should be documented as ``@bar:`` =20 In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -319,7 +320,7 @@ on a line of their own, like all other kernel-doc comme= nts:: Typedef documentation --------------------- =20 -The general format of a typedef kernel-doc comment is:: +The general format of a ``typedef`` kernel-doc comment is:: =20 /** * typedef type_name - Brief description. @@ -432,8 +433,8 @@ Domain`_ references. Typedef reference. =20 ``&struct_name->member`` or ``&struct_name.member`` - Structure or union member reference. The cross-reference will be to the = struct - or union definition, not the member directly. + ``struct`` or ``union`` member reference. The cross-reference will be to= the + ``struct`` or ``union`` definition, not the member directly. =20 ``&name`` A generic type reference. Prefer using the full reference described above @@ -537,7 +538,7 @@ identifiers: *[ function/type ...]* Include documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. - *type* can be a struct, union, enum, or typedef identifier. + *type* can be a ``struct``, ``union``, ``enum``, or ``typedef`` identifi= er. =20 Examples:: =20 --=20 2.51.1 From nobody Tue Dec 2 01:03:04 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 851652F7AD7; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; cv=none; b=Bbw3j8kYajxTPXt/ZUjVwZcsOAspXqklQHC5EUagQjuqsW0O6qkVzbXxMSxkPyyKy332scd5/UzJu3wXYH9wz4q1K9Xm/wT1+L0iMw2vUOlyung96VJPD126+9hvJZZzU3BkW77YScvJiksFUgITxZSe7e2fLmcuiuRkWek7GTM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1763978276; c=relaxed/simple; bh=WiyWZu0I2v9Q5Kn5QLFrux4dYHtK/j2mUZCTGm3fUBY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nSb+ccCBX8rctwA8KM4syhn3KIOF73mfHSKhET6BJwfw+EHm/v9WrCc1AHAK6lRn5JSfrwjZj61+W9dNNTormEW+1yiThM7JYvvor4rxdWj5XHGMplswxTKjRxW7PmptTYrFH4QMStclEndAFpH3z4MQXI4TVwXbEPvr3WpSXQw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=aUwF2xsL; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="aUwF2xsL" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1F128C2BCB0; Mon, 24 Nov 2025 09:57:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1763978276; bh=WiyWZu0I2v9Q5Kn5QLFrux4dYHtK/j2mUZCTGm3fUBY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aUwF2xsLXz6xp9s6ey5tbsqum6f8QBDM8Ldnzs99c/BnVd/r73gdFQh+EzbTo8yjw us5tfFqguhd5x/kOFkogaHaJem6d4L/qPMwNnF3Ft97mNjJTpHMv+dX0cXQLHd9lJS geqIWRscyvQSV36d90/zogmNRAYYudqCd9wMulyEFWY1UtLDbl0WtJ+wB6VgbTWyMX 9L2CSNsjw5+RhrTT2HBvI+EcSP9FvmfFxZpkBT1HHRMytqRAbaGurW9DPQfiHC/s7S EKTvYc2CMR5cDlDxf8Xf3sRNaOcFWjiRFlJaW5kyBUcsZTFV1pDMhdU9Hu1lzLN0fG WndlrTudDdNyw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vNTKU-000000013cH-0yk3; Mon, 24 Nov 2025 10:57:54 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Randy Dunlap" , linux-kernel@vger.kernel.org Subject: [PATCH v5 5/5] docs: kernel-doc.rst: document the new "var" kernel-doc markup Date: Mon, 24 Nov 2025 10:57:46 +0100 Message-ID: <5291dedbe9aa0104764a31fe2bf2b08d675295d5.1763978209.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Add a description containing the new syntax to document variables within kernel-doc markups. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Randy Dunlap --- Documentation/doc-guide/kernel-doc.rst | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-gui= de/kernel-doc.rst index 2e18a810f98b..0de0e344e10d 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -342,6 +342,18 @@ Typedefs with function prototypes can also be document= ed:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); =20 +Variables documentation +----------------------- + +The general format of a kernel-doc variable comment is:: + + /** + * var var_name - Brief description. + * + * Description of the var_name variable. + */ + extern int var_name; + Object-like macro documentation ------------------------------- =20 @@ -463,14 +475,18 @@ through the following syntax:: =20 For further details, please refer to the `Sphinx C Domain`_ documentation. =20 +.. note:: + Variables aren't automatically cross referenced. For those, you need to + explicitly add a C domain cross-reference. + Overview documentation comments ------------------------------- =20 To facilitate having source code and comments close together, you can incl= ude kernel-doc documentation blocks that are free-form comments instead of bei= ng -kernel-doc for functions, structures, unions, enums, or typedefs. This cou= ld be -used for something like a theory of operation for a driver or library code= , for -example. +kernel-doc for functions, structures, unions, enums, typedefs or variables. +This could be used for something like a theory of operation for a driver or +library code, for example. =20 This is done by using a ``DOC:`` section keyword with a section title. =20 @@ -538,7 +554,8 @@ identifiers: *[ function/type ...]* Include documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. - *type* can be a ``struct``, ``union``, ``enum``, or ``typedef`` identifi= er. + *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` + identifier. =20 Examples:: =20 --=20 2.51.1