VOP_PATHCONF.9: add a LOCKS section

[asomers]

Summary

MFC after: 2 weeks

[bjk]

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.

[jhb]

I echo pretty much all that Benjamin said. It would be nice if there was some way to auto-generate VOP locking documentation requirements from vnode_if.src in some way.

[asomers]

In D27842#622376, @jhb wrote:

I echo pretty much all that Benjamin said. It would be nice if there was some way to auto-generate VOP locking documentation requirements from vnode_if.src in some way.

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.

[asomers]

Fixed by https://cgit.freebsd.org/src/commit/?id=68de3bb59f64a37f3473517a56c2767e652c36b8

[bjk]

In D27842#622724, @asomers wrote:

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.

I had assumed that everyone just looked at the annotations in vnode_if.src ... is there something else I should be doing?