Re: [PATCH v5 05/11] kernel/api: add API specification for sys_open

On Thu, Oct 08, 2026 at 10:37:59AM -0400, Sasha Levin wrote:

On Thu, Oct 08, 2026 at 09:20:01AM -0500, Serge E. Hallyn wrote:

quoted

On Thu, Oct 08, 2026 at 09:13:38AM -0400, Gregory Price wrote:

quoted

On Thu, Oct 08, 2026 at 07:49:34AM -0500, Serge E. Hallyn wrote:

quoted

On Thu, Oct 08, 2026 at 04:49:45AM -0400, Sasha Levin wrote:

quoted

Add KAPI-annotated kerneldoc for the sys_open system call in fs/open.c.

The specification documents parameter constraints (pathname, flags
bitmask, permission mode), 24 error conditions, locking requirements,
side effects, required capabilities, and usage examples.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>

I know Kees and Jonathan and others asked for exactly this.  But one
downside to this is it makes just paging through fs/open.c a lot more
painful.  Maybe it's worth it.  Maybe "noone will ever do that again" bc
that's why we have ai and tools.  But a) that's how I've historically
done a lot of code research, b) IMO something like a manpages section 2
under Documentation/ would be a great place for this, and c) we can also
use tools to always sync these, or even show/edit in a single view when
you want  ('kdocedit fs/open.c').

In many, many other projects i've worked on, these docs are placed in
the header as opposed to the .c file, but I understand there is some
pain that comes with ifdef.

Keeping it in the header ties the definition to exactly the location
external users import to find the function - so it makes sense.

But separating the contracts from the code guarantees they'll go stale,

My plan is to be able to have the more detailed part of these specs somewhere
else, specially as they will grow some more, but I didn't want to add this
complexity right now.

quoted

OTOH these descriptions are so long that IMO they are guaranteed to go
stale anyway :)  While I'm editing a return value at the bottom of the
fn, most or all of the description is already going to be off my
terminal.

quoted

so I don't think shoving it in Documentation/ does anyone any good.

If every build auto-generates an update and then looks for and flags
meaningful changes (API breakages), then a) that is more reliable and b)
it doesn't matter where the docs are.

Even if there's just a three line comment above a fn, history proves
that it will not reliably stay in sync as the fn changes.  An automation
step/check is needed.

Please see CONFIG_KAPI_RUNTIME_CHECKS added by this series.

My point was just that whether the docs are inline or not, they will go
stale without that automation.  So if that's the case, then the docs do
not need to be inline.