Re: [PATCH v3 3/7] shm: add memfd_create() syscall

[John Stultz]

On Fri, Jun 13, 2014 at 7:20 AM, Michael Kerrisk (man-pages)
<mtk.manpages@xxxxxxxxx> wrote:
>
> The general notion these days is that a (comprehensive) manual page
> _should_ come *with* the system call, rather than after the fact. And
> there's a lot of value in that. I've found no end of bugs and design
> errors while writing (comprehensive) man pages after the fact (by
> which time it's too late to fix the design errors), and also found
> quite a few of those issues when I've managed to work with folk at the
> same time as they write the syscall. Bottom line: you really should
> write formal documentation now, as part of the process of code
> submission. It improves the chance of finding implementation and
> design bugs, and may well widen your circle of reviewers.

I very much agree here. One practical issue I've noticed is that
having separate targets for both the code changes and the manpages can
be an extra barrier for folks getting changes correctly documented as
the change is being submitted. Reviewers may say "be sure to send
updates to the man pages" but its not always easy to remember to
follow up and make sure the submitter got the changes (which match the
merged patches) to you as well.

I've been thinking it might be nice to have the kernel syscall man
pages included in the kernel source tree, then have them
copied/imported over to the man-pages project (similar to how glibc
imports uapi kernel headers).  They could even be kept in the
include/uapi directory, and checkpatch could ensure that changes that
touch include/uapi also have modifications to something in the
manpages directory. This way folks would be able to include the man
page change with the code change, making it easier for developers to
do the right thing, making it easier for reviewers to ensure its
correct, and making it easier for maintainers to ensure man page
documentation is properly in sync.

Or is this something that has been hashed over already? I do admit
this would disrupt your process a bit.

thanks
-john
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/