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-fsdevel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
