You use two spaces after a period in the comment below.

I don't quite follow: what's the second connection here?

The one that swapon opens, and keeps internally, and closes when swapoff gets called eventually.

If 'connection' isn't the right word, I'll take a suggestion a better one, but there's some count we're preventing from falling to zero, and if it's not "connections", what is it?

In GEOM terminology these references/connections create "consumers" of the GELI "provider" corresponding to the device. It might be clearer to write something like, "Do not close the device until the swap pager has attempted to create another consumer. For GELI devices created with the 'detach -l' option, removing the last consumer causes the device to be detached - that is, to disappear. This ordering ensures that the device will not be detached until swapoff is called."

Open a descriptor to create a GEOM consumer of the device.

Start using the device for swapping, which implicitly creates a second GEOM consumer.

I can't find documentation that assures me that swapon is only ever applied to GEOM devices, or consumers of devices, or whatever. So before I apply the suggested changes, I need some assurance that the rewritten comments will be true for all cases, not just geli cases.

Indeed, the swap pager can be configured to swap directly to a file rather than a GEOM. See sys_swapon(), which calls swapongeom() or swaponvp().

So, this comment is a bit misleading for the reason stated above: "name" might not refer to a GEOM device, but instead a regular file.

man (8) swapon says:
The swapon, swapoff and swapctl utilities are used to control swap

devices in the system.

man (2) swapon says:
The swapon() system call makes the block device special available to the

system for allocation for paging and swapping.

So "device" and "swapon" are pretty closely linked, and I don't see another word to use.

Perhaps the problem is not in the comments, but rather that swapon_trim has been written so that it does not fail when "name" identifies a file instead of a device. Or maybe there is no problem.