From 6d009bd85fa4e6dbad869e1cb707404968f3f20d Mon Sep 17 00:00:00 2001 From: Sasha Levin Date: Tue, 19 Aug 2025 11:52:10 -0400 Subject: kernel/api: enable kerneldoc-based API specifications Add support for extracting API specifications from kernel-doc comments and generating C macro invocations for the kernel API specification framework. Changes include: - New kdoc_apispec.py module for generating API spec macros - Updates to tools/docs/kernel-doc to support the -apispec output format - Build system integration in Makefile.build - Support for API-specific sections in kernel-doc comments kernel-doc recognises the KAPI sections only in -apispec mode, so its other output formats are unchanged. With CONFIG_KAPI_SPEC=y, Kbuild generates .apispec.h for each built source that has a contexts: or context-flags: line plus another KAPI section, and force-includes it when compiling that source. Assisted-by: LLM Signed-off-by: Sasha Levin --- tools/docs/kernel-doc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index d9192c3f1645..4c45c0d6cfa9 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -250,6 +250,8 @@ def main(): help="Output reStructuredText format (default).") out_fmt.add_argument("-N", "-none", "--none", action="store_true", help="Do not output documentation, only warnings.") + out_fmt.add_argument("-apispec", "--apispec", action="store_true", + help="Output C macro invocations for kernel API specifications.") out_fmt.add_argument("-y", "--yaml-file", "--yaml", help="Stores kernel-doc output on a yaml file.") @@ -326,6 +328,7 @@ def main(): # from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 + from kdoc.kdoc_apispec import ApiSpecFormat # pylint: disable=C0415 yaml_content = set() if args.yaml_file: @@ -351,12 +354,16 @@ def main(): out_style = None n_outputs += 1 + if args.apispec: + out_style = ApiSpecFormat() + n_outputs += 1 + if args.rst or n_outputs == 0: n_outputs += 1 out_style = RestFormat() if n_outputs > 1: - parser.error("Those arguments are muttually exclusive: --man, --rst, --none, except when generating a YAML file.") + parser.error("Those arguments are muttually exclusive: --man, --rst, --none, --apispec, except when generating a YAML file.") elif not n_outputs: out_style = RestFormat() @@ -365,7 +372,8 @@ def main(): yaml_file=args.yaml_file, yaml_content=yaml_content, out_style=out_style, werror=args.werror, wreturn=args.wreturn, wshort_desc=args.wshort_desc, - wcontents_before_sections=args.wcontents_before_sections) + wcontents_before_sections=args.wcontents_before_sections, + apispec=args.apispec) kfiles.parse(args.files, export_file=args.export_file) -- cgit v1.2.3