More precise documentation of optimizer settings and their defaults

docs/using-the-compiler.rst

@@ -281,63 +281,67 @@ Input Description
         "remappings": [ ":g=/dir" ],
         // Optional: Optimizer settings
         "optimizer": {
-          // Disabled by default.
-          // NOTE: enabled=false still leaves some optimizations on. See comments below.
-          // WARNING: Before version 0.8.6 omitting the 'enabled' key was not equivalent to setting
-          // it to false and would actually disable all the optimizations.
+          // Turn on the optimizer. Optional. Default: false.
+          // NOTE: The state of the optimizer is fully determined by the 'details' dict and this setting
+          // only affects its defaults - when enabled, all components default to being enabled.
+          // The opposite is not true - there are several components that always default to being
+          // enabled an can only be explicitly disabled via 'details'.
+          // WARNING: Before version 0.8.6 omitting this setting was not equivalent to setting
+          // it to false and would result in all components being disabled instead.
           "enabled": true,
-          // Optimize for how many times you intend to run the code.
+          // Optimize for how many times you intend to run the code. Optional. Default: 200.
           // Lower values will optimize more for initial deployment cost, higher
           // values will optimize more for high-frequency usage.
           "runs": 200,
-          // Switch optimizer components on or off in detail.
-          // The "enabled" switch above provides two defaults which can be
-          // tweaked here. If "details" is given, "enabled" can be omitted.
+          // State of all optimizer components. Optional.
+          // Default values are determined by whether the optimizer is enabled or not.
+          // Note that the 'enabled' setting only affects the defaults here and has no effect when
+          // all values are provided explicitly.
           "details": {
-            // The peephole optimizer is always on if no details are given,
-            // use details to switch it off.
+            // Peephole optimizer (opcode-based). Optional. Default: true.
+            // NOTE: Always runs (even with optimization disabled) unless explicitly turned off here.
             "peephole": true,
-            // The inliner is always off if no details are given,
-            // use details to switch it on.
+            // Inliner (opcode-based). Optional. Default: true when optimization is enabled.
             "inliner": false,
-            // The unused jumpdest remover is always on if no details are given,
-            // use details to switch it off.
+            // Unused JUMPDEST remover (opcode-based). Optional. Default: true.
+            // NOTE: Always runs (even with optimization disabled) unless explicitly turned off here.
             "jumpdestRemover": true,
-            // Sometimes re-orders literals in commutative operations.
+            // Literal reordering (codegen-based). Optional. Default: true when optimization is enabled.
+            // Moves literals to the right of commutative binary operators during code generation, helping exploit associativity.
             "orderLiterals": false,
-            // Removes duplicate code blocks
+            // Block deduplicator (opcode-based). Optional. Default: true when optimization is enabled.
+            // Unifies assembly code blocks that share content.
             "deduplicate": false,
-            // Common subexpression elimination, this is the most complicated step but
-            // can also provide the largest gain.
+            // Common subexpression elimination (opcode-based). Optional. Default: true when optimization is enabled.
+            // This is the most complicated step but can also provide the largest gain.
             "cse": false,
-            // Optimize representation of literal numbers and strings in code.
+            // Constant optimizer (opcode-based). Optional. Default: true when optimization is enabled.
+            // Tries to find better representations of literal numbers and strings, that satisfy the
+            // size/cost trade-off determined by the 'runs' setting.
             "constantOptimizer": false,
-            // Use unchecked arithmetic when incrementing the counter of for loops
-            // under certain circumstances. It is always on if no details are given.
+            // Unchecked loop increment (codegen-based). Optional. Default: true.
+            // Use unchecked arithmetic when incrementing the counter of 'for' loops under certain circumstances.
+            // NOTE: Always runs (even with optimization disabled) unless explicitly turned off here.
             "simpleCounterForLoopUncheckedIncrement": true,
-            // The new Yul optimizer. Mostly operates on the code of ABI coder v2
-            // and inline assembly.
-            // It is activated together with the global optimizer setting
-            // and can be deactivated here.
-            // Before Solidity 0.6.0 it had to be activated through this switch.
+            // Yul optimizer. Optional. Default: true when optimization is enabled.
+            // Used to optimize the IR produced by the Yul IR-based pipeline as well as inline assembly
+            // and utility Yul code generated by the compiler.
+            // NOTE: Before Solidity 0.6.0 the default was false.
             "yul": false,
-            // Tuning options for the Yul optimizer.
+            // Tuning options for the Yul optimizer. Optional.
             "yulDetails": {
               // Improve allocation of stack slots for variables, can free up stack slots early.
-              // Activated by default if the Yul optimizer is activated.
+              // Optional. Default: true if Yul optimizer is enabled.
               "stackAllocation": true,
-              // Select optimization steps to be applied. It is also possible to modify both the
-              // optimization sequence and the clean-up sequence. Instructions for each sequence
-              // are separated with the ":" delimiter and the values are provided in the form of
-              // optimization-sequence:clean-up-sequence. For more information see
-              // "The Optimizer > Selecting Optimizations".
-              // This field is optional, and if not provided, the default sequences for both
-              // optimization and clean-up are used. If only one of the sequences is provided
-              // the other will not be run.
-              // If only the delimiter ":" is provided then neither the optimization nor the clean-up
-              // sequence will be run.
-              // If set to an empty value, only the default clean-up sequence is used and
-              // no optimization steps are applied.
+              // Optimization step sequence.
+              // The general form of the value is "<main sequence>:<cleanup sequence>".
+              // The setting is optional and when omitted, default values are used for both sequences.
+              // If the value does not contain the ':' delimiter, it is interpreted as the main
+              // sequence and the default is used for the cleanup sequence.
+              // To make one of the sequences empty, the delimiter must be present at the first or last position.
+              // In particular if the whole value consists only of the delimiter, both sequences are empty.
+              // Note that there are several hard-coded steps that always run, even when both sequences are empty.
+              // For more information see "The Optimizer > Selecting Optimizations".
               "optimizerSteps": "dhfoDgvulfnTUtnIf..."
             }
           }

libsolidity/interface/OptimiserSettings.h

@@ -149,11 +149,11 @@ struct OptimiserSettings
 	/// Constant optimizer, which tries to find better representations that satisfy the given
 	/// size/cost-trade-off.
 	bool runConstantOptimiser = false;
-	/// Perform more efficient stack allocation for variables during code generation from Yul to bytecode.
+	/// Allow unchecked arithmetic when incrementing the counter of certain kinds of 'for' loop
 	bool simpleCounterForLoopUncheckedIncrement = false;
-	/// Yul optimiser with default settings. Will only run on certain parts of the code for now.
+	/// Perform more efficient stack allocation for variables during code generation from Yul to bytecode.
 	bool optimizeStackAllocation = false;
-	/// Allow unchecked arithmetic when incrementing the counter of certain kinds of 'for' loop
+	/// Yul optimiser with default settings. Will only run on certain parts of the code for now.
 	bool runYulOptimiser = false;
 	/// Sequence of optimisation steps to be performed by Yul optimiser.
 	/// Note that there are some hard-coded steps in the optimiser and you cannot disable