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

On Thu, Oct 08, 2026 at 11:16:46AM -0500, Serge E. Hallyn wrote:

On Thu, Oct 08, 2026 at 05:12:05PM +0100, David Laight wrote:

quoted

On Thu, 8 Oct 2026 09:20:01 -0500
"Serge E. Hallyn" [off-list ref] wrote:

...

quoted

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.

The only way it can possibly stay in step is to have the compiler process
the same source text.
Then, if you add/change a function parameter you'd be pretty much forced
to add/change the comment.
Return values would have to be documented at the C return statement and
really as an extra parameter to the return.

But, IMHO, the whole thing adds too much bloat to the source files.
When you 'grep' a source file, you don't really want another match in
a big comment at the top of every function.

I guess I don't mind either way: I heard both sides of this argument, and the
spec workflow is okay with either, so if the relevant maintainer asks for
changes here I'm more than happy to reformat this.

Which is, I think, the advantage here: it works just fine for the various
"kingdoms" we have in kernel-land.

-- 
Thanks,
Sasha