Add a overview comment to CmmCreateSwitchPlan

that explains its purpose and the division between CmmCreateSwitchPlan
and CmmSwitch.

1 files changed, 15 insertions, 0 deletions

diff --git a/compiler/cmm/CmmCreateSwitchPlans.hs b/compiler/cmm/CmmCreateSwitchPlans.hs
index 570ed6efb2..1b3ecb4443 100644
--- a/compiler/cmm/CmmCreateSwitchPlans.hs
+++ b/compiler/cmm/CmmCreateSwitchPlans.hs
@@ -14,6 +14,21 @@ import CmmSwitch
 import UniqSupply
 import DynFlags
 
+
+--
+-- This module replaces Switch statements as generated by the Stg -> Cmm
+-- transformation, which might be huge and sparse and hence unsuitable for
+-- assembly code, by proper constructs (if-then-else trees, dense jump tables).
+--
+-- The actual, abstract strategy is determined by createSwitchPlan in
+-- CmmSwitch and returned as a SwitchPlan; here is just the implementation in
+-- terms of Cmm code. See Note [Cmm Switches, the general plan] in CmmSwitch.
+--
+-- This division into different modules is both to clearly separte concerns, 
+-- but also because createSwitchPlan needs access to the constructors of
+-- SwitchTargets, a data type exported abstractly by CmmSwitch.
+--
+
 cmmCreateSwitchPlans :: DynFlags -> CmmGraph -> UniqSM CmmGraph
 cmmCreateSwitchPlans dflags g = do
     blocks' <- concat <$> mapM (visitSwitches dflags) (toBlockList g)