[partition] Document intention of new-style swap config

src/modules/partition/gui/PartitionViewStep.cpp

@@ -487,25 +487,36 @@ PartitionViewStep::setConfigurationMap( const QVariantMap& configurationMap )
         gs->insert( "efiSystemPartition", QStringLiteral( "/boot/efi" ) );
     }
 
+    // SWAP SETTINGS
+    //
+    // This is a bit convoluted because there's legacy settings to handle as well
+    // as the new-style list of choices, with mapping back-and-forth.
+    if ( configurationMap.contains( "userSwapChoices" ) &&
+        ( configurationMap.contains( "ensureSuspendToDisk" ) || configurationMap.contains( "neverCreateSwap" ) ) )
+        cError() << "Partition-module configuration mixes old- and new-style swap settings.";
+
+    bool ensureSuspendToDisk = true;
+    if ( configurationMap.contains( "ensureSuspendToDisk" ) )
+        cWarning() << "Partition-module setting *ensureSuspendToDisk* is deprecated.";
     if ( configurationMap.contains( "ensureSuspendToDisk" ) &&
          configurationMap.value( "ensureSuspendToDisk" ).type() == QVariant::Bool )
-    {
-        gs->insert( "ensureSuspendToDisk", configurationMap.value( "ensureSuspendToDisk" ).toBool() );
-    }
+        ensureSuspendToDisk = configurationMap.value( "ensureSuspendToDisk" ).toBool();
     else
-    {
-        gs->insert( "ensureSuspendToDisk", true );
-    }
+        ensureSuspendToDisk = true;
 
+    bool neverCreateSwap = false;
+    if ( configurationMap.contains( "neverCreateSwap" ) )
+        cWarning() << "Partition-module setting *neverCreateSwap* is deprecated.";
     if ( configurationMap.contains( "neverCreateSwap" ) &&
          configurationMap.value( "neverCreateSwap" ).type() == QVariant::Bool )
-    {
-        gs->insert( "neverCreateSwap", configurationMap.value( "neverCreateSwap" ).toBool() );
-    }
+        neverCreateSwap = configurationMap.value( "neverCreateSwap" ).toBool();
     else
-    {
-        gs->insert( "neverCreateSwap", false );
-    }
+        neverCreateSwap = false;
+
+    // These gs settings seem to be unused (in upstream Calamares) outside of
+    // the partition module itself.
+    gs->insert( "ensureSuspendToDisk", ensureSuspendToDisk );
+    gs->insert( "neverCreateSwap", neverCreateSwap );
 
     if ( configurationMap.contains( "drawNestedPartitions" ) &&
          configurationMap.value( "drawNestedPartitions" ).type() == QVariant::Bool )

src/modules/partition/partition.conf

@@ -3,28 +3,37 @@
 # etc.) use just /boot.
 efiSystemPartition:     "/boot/efi"
 
-# Make sure an autogenerated swap partition is big enough for hibernation in
-# automated partitioning modes. Swap can be disabled through *neverCreateSwap*.
+# In autogenerated partitioning, allow the user to select a swap size?
+# If there is exactly one choice, no UI is presented, and the user
+# cannot make a choice -- this setting is used. If there is more than
+# one choice, a UI is presented.
 #
-#  - *neverCreateSwap* is true: no swap is created
-#  - *neverCreateSwap* is false (the default): swap is created, as follows:
-#    - *ensureSuspendToDisk* is true (default): Swap is always at least total
-#      memory size, and up to 4GiB RAM follows the rule-of-thumb 2 * memory;
+# Legacy settings *neverCreateSwap* and *ensureSuspendToDisk* correspond
+# to values of *userSwapChoices* as follows:
+#    - *neverCreateSwap* is true, means [none]
+#    - *neverCreateSwap* is false, *ensureSuspendToDisk* is false, [small]
+#    - *neverCreateSwap* is false, *ensureSuspendToDisk* is true, [suspend]
+#
+# Autogenerated swap sizes are as follows:
+#    - *suspend*: Swap is always at least total memory size,
+#      and up to 4GiB RAM follows the rule-of-thumb 2 * memory;
 #      from 4GiB to 8 GiB it stays steady at 8GiB, and over 8 GiB memory
 #      swap is the size of main memory.
-#    - *ensureSuspendToDisk* is false: Follows the rules above, but Swap is at
+#    - *small*: Follows the rules above, but Swap is at
 #      most 8GiB, and no more than 10% of available disk.
-#    In both cases, a fudge factor (usually 10% extra) is applied so that there
-#    is some space for administrative overhead (e.g. 8 GiB swap will allocate
-#    8.8GiB on disk in the end).
-#
-# Default is true.
-ensureSuspendToDisk:    true
+# In both cases, a fudge factor (usually 10% extra) is applied so that there
+# is some space for administrative overhead (e.g. 8 GiB swap will allocate
+# 8.8GiB on disk in the end).
+userSwapChoices:
+    - none      # Create no swap, use no swap
+    # - reuse     # Re-use existing swap, but don't create any
+    - small     # Up to 4GB
+    - suspend   # At least main memory size
+    # - file      # To swap file instead of partition (unsupported right now)
 
-# Never create swap partitions in automated partitioning modes.
-# If this is true, ensureSuspendToDisk is ignored.
-# Default is false.
-neverCreateSwap:        false
+# LEGACY SETTINGS (these will generate a warning)
+# ensureSuspendToDisk:    true
+# neverCreateSwap:        false
 
 # Correctly draw nested (e.g. logical) partitions as such.
 drawNestedPartitions:   false