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

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

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.

David

That's why I feel all this info that Sasha has added should go into a
Documentation/uapi/ autogenerated directory.  Auto-updated on every build,
with warnings if the result has changed.

-serge