Improve documentation of homebrew module

modules/homebrew.nix

@@ -70,14 +70,15 @@ let
         example = "uninstall";
         description = ''
           This option manages what happens to formulae installed by Homebrew, that aren't present in
-          the Brewfile generated by this module, during <command>nix-darwin</command> activation.
+          the Brewfile generated by this module, during <command>nix-darwin</command> system
+          activation.
 
           When set to <literal>"none"</literal> (the default), formulae not present in the generated
           Brewfile are left installed.
 
           When set to <literal>"uninstall"</literal>, <command>nix-darwin</command> invokes
           <command>brew bundle [install]</command> with the <command>--cleanup</command> flag. This
-          uninstalls all formulae not listed in generate Brewfile, i.e.,
+          uninstalls all formulae not listed in generated Brewfile, i.e.,
           <command>brew uninstall</command> is run for those formulae.
 
           When set to <literal>"zap"</literal>, <command>nix-darwin</command> invokes
@@ -96,10 +97,14 @@ let
         default = false;
         description = ''
           Whether to enable Homebrew to auto-update itself and all formulae during
-          <command>nix-darwin</command> activation. The default is <literal>false</literal> so that
+          <command>nix-darwin</command> system activation. The default is <literal>false</literal>
-          repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
+          so that repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
 
           Note that Homebrew auto-updates when it's been more then 5 minutes since it last updated.
+
+          Although auto-updating is disabled by default during system activation, note that Homebrew
+          will auto-update when you manually invoke certain Homebrew commands. To modify this
+          behavior see ${mkDocOptionLink "homebrew.global.autoUpdate"}.
         '';
       };
       upgrade = mkOption {
@@ -107,8 +112,8 @@ let
         default = false;
         description = ''
           Whether to enable Homebrew to upgrade outdated formulae and Mac App Store apps during
-          <command>nix-darwin</command> activation. The default is <literal>false</literal> so
+          <command>nix-darwin</command> system activation. The default is <literal>false</literal>
-          that repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
+          so that repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
         '';
       };
 
@@ -330,7 +335,8 @@ let
         description = ''
           Target location for Audio Unit Plugins.
 
-          Homebrew's default is <filename class='directory'>~/Library/Audio/Plug-Ins/Components</filename>.
+          Homebrew's default is
+          <filename class='directory'>~/Library/Audio/Plug-Ins/Components</filename>.
         '';
       };
       vst_plugindir = mkNullOrStrOption {
@@ -363,7 +369,11 @@ let
         example = "zh-TW";
       };
       require_sha = mkNullOrBoolOption {
-        description = "Whether to require cask(s) to have a checksum.";
+        description = ''
+          Whether to require cask(s) to have a checksum.
+
+          Homebrew's default is <literal>false</literal>.
+        '';
       };
       no_quarantine = mkNullOrBoolOption {
         description = "Whether to disable quarantining of downloads.";
@@ -448,8 +458,8 @@ let
         brewfileLine =
           "brew ${sCfg.name}"
           + optionalString (sCfgSubset != { }) ", ${mkBrewfileLineOptionsListString sCfgSubset}"
-          # We need to handle the `restart_service` option seperately since it can be either bool
+          # We need to handle the `restart_service` option seperately since it can be either a bool
-          # or the string value "changed".
+          # or `:changed` in the Brewfile.
           + optionalString (sCfg ? restart_service) (
             ", restart_service: " + (
               if isBool config.restart_service then sCfg.restart_service
@@ -468,11 +478,16 @@ let
       args = mkOption {
         type = types.nullOr (types.submodule caskArgsOptions);
         default = null;
+        visible = "shallow"; # so that options from `homebrew.caskArgs` aren't repeated.
+        description = ''
+          Arguments passed to <command>brew install --cask</command> when installing this cask. See
+          ${mkDocOptionLink "homebrew.caskArgs"} for the available options.
+        '';
       };
       greedy = mkNullOrBoolOption {
         description = ''
-          Whether to always upgrade auto-updated or unversioned cask to the latest version even if
+          Whether to always upgrade this cask regardless of whether it's unversioned or it updates
-          it's already installed.
+          itself.
         '';
       };
 
@@ -502,11 +517,29 @@ in
 
   options.homebrew = {
     enable = mkEnableOption ''
-      configuring your Brewfile, and installing/updating the formulae therein via
+      <command>nix-darwin</command> to manage installing/updating/upgrading Homebrew taps, formulae,
-      the <command>brew bundle</command> command, using <command>nix-darwin</command>.
+      and casks, as well as Mac App Store apps and Docker containers, using Homebrew Bundle.
 
-      Note that enabling this option does not install Homebrew. See the Homebrew
+      Note that enabling this option does not install Homebrew, see the Homebrew
-      <link xlink:href="https://brew.sh">website</link> for installation instructions
+      <link xlink:href="https://brew.sh">website</link> for installation instructions.
+
+      Use the ${mkDocOptionLink "homebrew.brews"}, ${mkDocOptionLink "homebrew.casks"},
+      ${mkDocOptionLink "homebrew.masApps"}, and ${mkDocOptionLink "homebrew.whalebrews"} options
+      to list the Homebrew formulae, casks, Mac App Store apps, and Docker containers you'd like to
+      install. Use the ${mkDocOptionLink "homebrew.taps"} option, to make additional formula
+      repositories available to Homebrew. This module uses those options (along with the
+      ${mkDocOptionLink "homebrew.caskArgs"} options) to generate a Brewfile that
+      <command>nix-darwin</command> passes to the <command>brew bundle</command> command during
+      system activation.
+
+      The default configuration of this module prevents Homebrew Bundle from auto-updating Homebrew
+      and all formulae, as well as upgrading anything that's already installed, so that repeated
+      invocations of <command>darwin-rebuild switch</command> (without any change to the
+      configuration) are idempotent. You can modify this behavior using the options under
+      ${mkDocOptionLink "homebrew.onActivation"}.
+
+      This module also provides a few options for modifying how Homebrew commands behave when
+      you manually invoke them, under ${mkDocOptionLink "homebrew.global"}
     '';
 
     brewPrefix = mkOption {
@@ -558,7 +591,7 @@ in
         ]
       '';
       description = ''
-        Homebrew formula repositories to tap.
+        List of Homebrew formula repositories to tap.
 
         Taps defined as strings, e.g., <literal>"user/repo"</literal>, are a shorthand for:
 
@@ -575,7 +608,10 @@ in
           require_sha = true;
         }
       '';
-      description = "Arguments to apply to all <option>homebrew.casks</option>.";
+      description = ''
+        Arguments passed to <command>brew install --cask</command> for all casks listed in
+        ${mkDocOptionLink "homebrew.casks"}.
+      '';
     };
 
     brews = mkOption {
@@ -604,9 +640,9 @@ in
         ]
       '';
       description = ''
-        Homebrew brews to install.
+        List of Homebrew formulae to install.
 
-        Brews defined as strings, e.g., <literal>"imagemagick"</literal>, are a shorthand for:
+        Formulae defined as strings, e.g., <literal>"imagemagick"</literal>, are a shorthand for:
 
         <code>{ name = "imagemagick"; }</code>
       '';
@@ -635,7 +671,7 @@ in
         ]
       '';
       description = ''
-        Homebrew casks to install.
+        List of Homebrew casks to install.
 
         Casks defined as strings, e.g., <literal>"google-chrome"</literal>, are a shorthand for:
 
@@ -656,12 +692,12 @@ in
         Applications to install from Mac App Store using <command>mas</command>.
 
         When this option is used, <literal>"mas"</literal> is automatically added to
-        <option>homebrew.brews</option>.
+        ${mkDocOptionLink "homebrew.brews"}.
 
         Note that you need to be signed into the Mac App Store for <command>mas</command> to
         successfully install and upgrade applications, and that unfortunately apps removed from this
         option will not be uninstalled automatically even if
-        <option>homebrew.onActivation.cleanup</option> is set to <literal>"uninstall"</literal>
+        ${mkDocOptionLink "homebrew.onActivation.cleanup"} is set to <literal>"uninstall"</literal>
         or <literal>"zap"</literal> (this is currently a limitation of Homebrew Bundle).
 
         For more information on <command>mas</command> see:
@@ -674,10 +710,10 @@ in
       default = [ ];
       example = [ "whalebrew/wget" ];
       description = ''
-        Docker images to install using <command>whalebrew</command>.
+        List of Docker images to install using <command>whalebrew</command>.
 
         When this option is used, <literal>"whalebrew"</literal> is automatically added to
-        <option>homebrew.brews</option>.
+        ${mkDocOptionLink "homebrew.brews"}.
 
         For more information on <command>whalebrew</command> see:
         <link xlink:href="https://github.com/whalebrew/whalebrew">github.com/whalebrew/whalebrew</link>.
@@ -691,7 +727,7 @@ in
         # 'brew cask install' only if '/usr/libexec/java_home --failfast' fails
         cask "java" unless system "/usr/libexec/java_home --failfast"
       '';
-      description = "Extra lines to be added verbatim to bottom of the generated Brewfile.";
+      description = "Extra lines to be added verbatim to the bottom of the generated Brewfile.";
     };
 
     brewfile = mkInternalOption {
@@ -711,7 +747,7 @@ in
     ];
 
     warnings = [
-      (mkIf (options.homebrew.autoUpdate.isDefined || options.homebrew.cleanup.isDefined) "The `homebrew' module no longer upgrades outdated formulae and apps by default during `nix-darwin' activation. To enable upgrading, set `homebrew.onActivation.upgrade = true'.")
+      (mkIf (options.homebrew.autoUpdate.isDefined || options.homebrew.cleanup.isDefined) "The `homebrew' module no longer upgrades outdated formulae and apps by default during `nix-darwin' system activation. To enable upgrading, set `homebrew.onActivation.upgrade = true'.")
     ];
 
     homebrew.brews =