Merge pull request #11038 from keszybz/man-timeouts

Small improvements for documentation of timeout options

man/systemd.mount.xml

@@ -263,7 +263,7 @@
         for details.</para></listitem>
       </varlistentry>
 
-      <varlistentry>
+      <varlistentry id='device-timeout'>
         <term><option>x-systemd.device-timeout=</option></term>
 
         <listitem><para>Configure how long systemd should wait for a
@@ -303,7 +303,7 @@
       <varlistentry>
         <term><option>x-systemd.makefs</option></term>
 
-        <listitem><para>The file system or swap structure will be initialized
+        <listitem><para>The file system will be initialized
         on the device. If the device is not "empty", i.e. it contains any signature,
         the operation will be skipped. It is hence expected that this option
         remains set even after the device has been initalized.</para>

man/systemd.swap.xml

@@ -6,7 +6,9 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="systemd.swap">
+<refentry id="systemd.swap"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
   <refentryinfo>
     <title>systemd.swap</title>
     <productname>systemd</productname>
@@ -141,6 +143,26 @@
         successfully.</para>
         </listitem>
       </varlistentry>
+
+      <xi:include href="systemd.mount.xml" xpointer="device-timeout" />
+
+      <varlistentry>
+        <term><option>x-systemd.makefs</option></term>
+
+        <listitem><para>The swap structure will be initialized on the device. If the device is not
+        "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected
+        that this option remains set even after the device has been initalized.</para>
+
+        <para>Note that this option can only be used in <filename>/etc/fstab</filename>, and will be
+        ignored when part of the <varname>Options=</varname> setting in a unit file.</para>
+
+        <para>See
+        <citerefentry><refentrytitle>systemd-mkswap@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        and the discussion of
+        <citerefentry project='man-pages'><refentrytitle>wipefs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        in <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 

man/systemd.unit.xml

@@ -912,8 +912,6 @@
       <varlistentry>
         <term><varname>JobTimeoutSec=</varname></term>
         <term><varname>JobRunningTimeoutSec=</varname></term>
-        <term><varname>JobTimeoutAction=</varname></term>
-        <term><varname>JobTimeoutRebootArgument=</varname></term>
 
         <listitem><para>When a job for this unit is queued, a time-out <varname>JobTimeoutSec=</varname> may be
         configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually
@@ -925,12 +923,20 @@
         no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific
         timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however
         is useful to abort only the job waiting for the unit state to change.</para>
+        </listitem>
+      </varlistentry>
 
-        <para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when the time-out
-        is hit. It takes the same values as <varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
+      <varlistentry>
+        <term><varname>JobTimeoutAction=</varname></term>
+        <term><varname>JobTimeoutRebootArgument=</varname></term>
+
+        <listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when
+        the time-out is hit, see description of <varname>JobTimeoutSec=</varname> and
+        <varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
+        <varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
         <varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the
-        <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-        system call.</para></listitem>
+        <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>

src/shared/generator.c

@@ -197,10 +197,9 @@ int generator_write_timeouts(
                 const char *opts,
                 char **filtered) {
 
-        /* Allow configuration how long we wait for a device that
-         * backs a mount point to show up. This is useful to support
-         * endless device timeouts for devices that show up only after
-         * user input, like crypto devices. */
+        /* Configure how long we wait for a device that backs a mount point or a
+         * swap partition to show up. This is useful to support endless device timeouts
+         * for devices that show up only after user input, like crypto devices. */
 
         _cleanup_free_ char *node = NULL, *unit = NULL, *timeout = NULL;
         usec_t u;