MFC after: 2 weeks
- Group Reviewers
- R10:68de3bb59f64: VOP_PATHCONF.9: add a LOCKS section
I find it interesting that we have such a long history of a LOCKS section in VOP man pages, given that mdoc(7) includes a list of conventional manual sections, with note that "[t]hese sections should be used unless it's bsolutely necessary that custom sections be used."
Unrelatedly, I think I internalized from some discussion with kib years ago that the preferred way to document VFS locking requirements is with assertions in the code (or vnode_if.src), enforced via DEBUG_VFS_LOCKS.
Other documentation, whether in the form of function comments, man page entries, or otherwise, can become stale and are in some sense redundant.
But perhaps the long history of these sections also applies here :)
That said, the actual mechanics of the mdoc changes are fine.
Yeah. The other problem with using assertions to document the locking requirements is that the assertions only work for VOP callers. They don't help VOP implementors, like fusefs, to get it right.