home-environment: make home.activation public

Also improve documentation and add an example.

modules/home-environment.nix

@@ -235,17 +235,51 @@ in
     };
 
     home.activation = mkOption {
-      internal = true;
       type = dagOf types.str;
       default = {};
+      example = literalExample ''
+        {
+          myActivationAction = config.lib.dag.entryAfter ["writeBoundary"] '''
+            $DRY_RUN_CMD ln -s $VERBOSE_ARG \
+                ''${builtins.toPath ./link-me-directly} $HOME
+          ''';
+        }
+      '';
       description = ''
-        Activation scripts for the home environment.
+        The activation scripts blocks to run when activating a Home
+        Manager generation. Any entry here should be idempotent,
+        meaning running twice or more times produces the same result
+        as running it once.
+
         </para><para>
-        Any script should respect the <varname>DRY_RUN</varname>
-        variable, if it is set then no actual action should be taken.
+
+        If the script block produces any observable side effect, such
+        as writing or deleting files, then it
+        <emphasis>must</emphasis> be placed after the special
+        <literal>writeBoundary</literal> script block. Prior to the
+        write boundary one can place script blocks that verifies, but
+        does not modify, the state of the system and exits if an
+        unexpected state is found. For example, the
+        <literal>checkLinkTargets</literal> script block checks for
+        collisions between non-managed files and files defined in
+        <varname><link linkend="opt-home.file">home.file</link></varname>.
+
+        </para><para>
+
+        A script block should respect the <varname>DRY_RUN</varname>
+        variable, if it is set then the actions taken by the script
+        should be logged to standard out and not actually performed.
         The variable <varname>DRY_RUN_CMD</varname> is set to
-        <code>echo</code> if dry run is enabled. Thus, many cases you
-        can use the idiom <code>$DRY_RUN_CMD rm -rf /</code>.
+        <command>echo</command> if dry run is enabled.
+
+        </para><para>
+
+        A script block should also respect the
+        <varname>VERBOSE</varname> variable, and if set print
+        information on standard out that may be useful for debugging
+        any issue that may arise. The variable
+        <varname>VERBOSE_ARG</varname> is set to
+        <option>--verbose</option> if verbose output is enabled.
       '';
     };