nixos: Elaborate documentation for fileSystems.* options

doc/manpage-urls.json

@@ -16,6 +16,7 @@
   "environment.d(5)": "https://www.freedesktop.org/software/systemd/man/environment.d.html",
   "extension-release(5)": "https://www.freedesktop.org/software/systemd/man/extension-release.html",
   "file-hierarchy(7)": "https://www.freedesktop.org/software/systemd/man/file-hierarchy.html",
+  "fstab(5)": "https://man.archlinux.org/man/fstab.5",
   "gnunet.conf(5)": "https://docs.gnunet.org/latest/users/configuration.html",
   "group(5)": "https://man.archlinux.org/man/group.5",
   "halt(8)": "https://www.freedesktop.org/software/systemd/man/halt.html",
@@ -59,6 +60,7 @@
   "machinectl(1)": "https://www.freedesktop.org/software/systemd/man/machinectl.html",
   "mksquashfs(1)": "https://man.archlinux.org/man/extra/squashfs-tools/mksquashfs.1.en",
   "modules-load.d(5)": "https://www.freedesktop.org/software/systemd/man/modules-load.d.html",
+  "mount(8)": "https://man.archlinux.org/man/mount.8",
   "mount.ddi(1)": "https://www.freedesktop.org/software/systemd/man/mount.ddi.html",
   "mpd(1)": "https://mpd.readthedocs.io/en/latest/mpd.1.html",
   "mpd.conf(5)": "https://mpd.readthedocs.io/en/latest/mpd.conf.5.html",

nixos/modules/tasks/filesystems.nix

@@ -58,13 +58,20 @@ let
         mountPoint = mkOption {
           example = "/mnt/usb";
           type = nonEmptyWithoutTrailingSlash;
-          description = "Location of the mounted file system.";
+          default = name;
+          description = ''
+            Location where the file system will be mounted.
+
+            This is called `mountpoint` in {manpage}`mount(8)` and `fs_file` in {manpage}`fstab(5)`
+          '';
         };
 
         stratis.poolUuid = lib.mkOption {
           type = types.uniq (types.nullOr types.str);
           description = ''
             UUID of the stratis pool that the fs is located in
+
+            This is only relevant if you are using [stratis](https://stratis-storage.github.io/).
           '';
           example = "04c68063-90a5-4235-b9dd-6180098a20d9";
           default = null;
@@ -74,14 +81,29 @@ let
           default = null;
           example = "/dev/sda";
           type = types.nullOr nonEmptyStr;
-          description = "Location of the device.";
+          description = ''
+            The device as passed to `mount`.
+
+            This can be any of:
+
+            - a filename of a block special device such as `/dev/sdc3`
+            - a tag such as `UUID=fdd68895-c307-4549-8c9c-90e44c71f5b7`
+            - (for bind mounts only) the source path
+            - something else depending on the {option}`fsType`. For example, `nfs` device may look like `knuth.cwi.nl:/dir`
+
+            This is called `device` in {manpage}`mount(8)` and `fs_spec` in {manpage}`fstab(5)`.
+          '';
         };
 
         fsType = mkOption {
           default = "auto";
           example = "ext3";
           type = nonEmptyStr;
-          description = "Type of the file system.";
+          description = ''
+            Type of the file system.
+
+            This is the `fstype` passed to `-t` in the {manpage}`mount(8)` command, and is called `fs_vfstype` in {manpage}`fstab(5)`.
+          '';
         };
 
         options = mkOption {
@@ -89,7 +111,14 @@ let
           example = [ "data=journal" ];
           description = ''
             Options used to mount the file system.
-            See {manpage}`mount(8)` for common options.
+
+            This is called `options` in {manpage}`mount(8)` and `fs_mntops` in {manpage}`fstab(5)`
+
+            Some options that can be used for all mounts are documented in {manpage}`mount(8)` under `FILESYSTEM-INDEPENDENT MOUNT OPTIONS`.
+
+            Options that systemd understands are documented in {manpage}`systemd.mount(5)` under `FSTAB`.
+
+            Each filesystem supports additional options, see the docs for that filesystem.
           '';
           type = types.nonEmptyListOf nonEmptyStr;
         };
@@ -105,13 +134,14 @@ let
             to this list, any other filesystem whose mount point is a parent of
             the path will be mounted before this filesystem. The paths do not need
             to actually be the {option}`mountPoint` of some other filesystem.
+
+            This is useful for mounts which require keys and/or configuration files residing on another filesystem.
           '';
         };
 
       };
 
       config = {
-        mountPoint = mkDefault name;
         device = mkIf (elem config.fsType specialFSTypes) (mkDefault config.fsType);
       };
 
@@ -127,7 +157,12 @@ let
           default = null;
           example = "root-partition";
           type = types.nullOr nonEmptyStr;
-          description = "Label of the device (if any).";
+          description = ''
+            Label of the device. This simply sets {option}`device` to
+            `/dev/disk/by-id/''${label}`. Note that devices will not
+            have a label unless they contain a filesystem which
+            supports labels, such as ext4 or fat32.
+          '';
         };
 
         autoFormat = mkOption {