Em Mon, 30 Jun 2025 13:53:55 -0600
Jonathan Corbet [off-list ref] escreveu:

Sasha Levin [off-list ref] writes:

quoted

Add a comprehensive framework for formally documenting kernel APIs with
inline specifications. This framework provides:

- Structured API documentation with parameter specifications, return
  values, error conditions, and execution context requirements
- Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
- Export of specifications via debugfs for tooling integration
- Support for both internal kernel APIs and system calls

The framework stores specifications in a dedicated ELF section and
provides infrastructure for:
- Compile-time validation of specifications
- Runtime querying of API documentation
- Machine-readable export formats
- Integration with existing SYSCALL_DEFINE macros

This commit introduces the core infrastructure without modifying any
existing APIs. Subsequent patches will add specifications to individual
subsystems.

Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/admin-guide/kernel-api-spec.rst |  507 ++++++

You need to add that file to index.rst in that directory or it won't be
pulled into the docs build.

Wouldn't it be nice to integrate all this stuff with out existing
kerneldoc mechanism...? :)

+1

Having two different mechanisms (kapi and kerneldoc) makes a lot harder
to maintain kAPI.

Also, IGT (a testing tool for DRM subsystem) used to have a macro
based documentation system. It got outdated with time, as people
ends forgetting to update the macros when changing the code. 
Also, sometimes we want to add some rich text there, with graphs,
tables, ...

More important than that: people end not remembering to add such macros.
As kerneldoc markups are similar to Doxygen and normal C comments,
it is more likely that people will remember.

So, IMO the best would be to use kerneldoc syntax there, letting
Kerneldoc Sphinx extension handling it for docs, while having
tools to implement the other features you mentioned.

Thanks,
Mauro