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

[Serge E. Hallyn]

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" <serge@xxxxxxxxxx> wrote:
> 
> ...
> > 
> > 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