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

[Sasha Levin]

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:
> > 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.

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