diff options
| author | Ben Gamari <ben@smart-cactus.org> | 2022-01-30 08:45:49 -0500 |
|---|---|---|
| committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2022-02-01 12:29:26 -0500 |
| commit | 88fba8a4b3c22e953a634b81dd0b67ec66eb5e72 (patch) | |
| tree | 75a46332ad32cfeaf4f4d52b3b60fd452f2493b6 /compiler | |
| parent | 06185102bb06d6d56e00d40172a6a473fc228501 (diff) | |
| download | haskell-88fba8a4b3c22e953a634b81dd0b67ec66eb5e72.tar.gz | |
Fix a few Note inconsistencies
Diffstat (limited to 'compiler')
109 files changed, 232 insertions, 267 deletions
diff --git a/compiler/CodeGen.Platform.h b/compiler/CodeGen.Platform.h index ceccc38620..346dd0af03 100644 --- a/compiler/CodeGen.Platform.h +++ b/compiler/CodeGen.Platform.h @@ -834,7 +834,7 @@ freeReg :: RegNo -> Bool # if defined(MACHREGS_i386) freeReg esp = False -- %esp is the C stack pointer -freeReg esi = False -- Note [esi/edi/ebp not allocatable] +freeReg esi = False -- See Note [esi/edi/ebp not allocatable] freeReg edi = False freeReg ebp = False # endif @@ -844,7 +844,7 @@ freeReg rsp = False -- %rsp is the C stack pointer {- Note [esi/edi/ebp not allocatable] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ %esi is mapped to R1, so %esi would normally be allocatable while it is not being used for R1. However, %esi has no 8-bit version on x86, and the linear register allocator is not sophisticated enough to diff --git a/compiler/GHC/Builtin/Types.hs b/compiler/GHC/Builtin/Types.hs index 2096e27a2b..347afad5c0 100644 --- a/compiler/GHC/Builtin/Types.hs +++ b/compiler/GHC/Builtin/Types.hs @@ -762,7 +762,7 @@ constraintKind = mkTyConTy constraintKindTyCon * * ************************************************************************ -Note [How tuples work] See also Note [Known-key names] in GHC.Builtin.Names +Note [How tuples work] ~~~~~~~~~~~~~~~~~~~~~~ * There are three families of tuple TyCons and corresponding DataCons, expressed by the type BasicTypes.TupleSort: @@ -814,6 +814,8 @@ Note [How tuples work] See also Note [Known-key names] in GHC.Builtin.Names deserialization we lookup the Name associated with the unique with the logic in GHC.Builtin.Uniques. See Note [Symbol table representation of names] for details. +See also Note [Known-key names] in GHC.Builtin.Names. + Note [One-tuples] ~~~~~~~~~~~~~~~~~ GHC supports both boxed and unboxed one-tuples: diff --git a/compiler/GHC/Builtin/Uniques.hs b/compiler/GHC/Builtin/Uniques.hs index dc70ce3f5c..acf835c996 100644 --- a/compiler/GHC/Builtin/Uniques.hs +++ b/compiler/GHC/Builtin/Uniques.hs @@ -143,7 +143,6 @@ getUnboxedSumName n -- Note [Uniques for tuple type and data constructors] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Wired-in type constructor keys occupy *two* slots: -- * u: the TyCon itself -- * u+1: the TyConRepName of the TyCon @@ -156,7 +155,6 @@ getUnboxedSumName n {- Note [Unique layout for constraint tuple selectors] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Constraint tuples, like boxed and unboxed tuples, have their type and data constructor Uniques wired in (see Note [Uniques for tuple type and data constructors]). Constraint tuples are diff --git a/compiler/GHC/Builtin/primops.txt.pp b/compiler/GHC/Builtin/primops.txt.pp index 32e185e3a9..772371235e 100644 --- a/compiler/GHC/Builtin/primops.txt.pp +++ b/compiler/GHC/Builtin/primops.txt.pp @@ -149,7 +149,6 @@ defaults -- Note [When do out-of-line primops go in primops.txt.pp] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Out of line primops are those with a C-- implementation. But that -- doesn't mean they *just* have an C-- implementation. As mentioned in -- Note [Inlining out-of-line primops and heap checks], some out-of-line @@ -2437,7 +2436,6 @@ primop WriteMutVarOp "writeMutVar#" GenPrimOp -- Note [Why not an unboxed tuple in atomicModifyMutVar2#?] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Looking at the type of atomicModifyMutVar2#, one might wonder why -- it doesn't return an unboxed tuple. e.g., -- @@ -3173,7 +3171,6 @@ primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp -- Note [reallyUnsafePtrEquality# can_fail] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- reallyUnsafePtrEquality# can't actually fail, per se, but we mark it -- can_fail anyway. Until 5a9a1738023a, GHC considered primops okay for -- speculation only when their arguments were known to be forced. This was @@ -3264,7 +3261,7 @@ primop DataToTagOp "dataToTag#" GenPrimOp a -> Int# -- Zero-indexed; the first constructor has tag zero with strictness = { \ _arity -> mkClosedDmdSig [evalDmd] topDiv } - -- See Note [dataToTag# magic] in GHC.Core.Op.ConstantFold + -- See Note [dataToTag# magic] in GHC.Core.Opt.ConstantFold primop TagToEnumOp "tagToEnum#" GenPrimOp Int# -> a diff --git a/compiler/GHC/ByteCode/Types.hs b/compiler/GHC/ByteCode/Types.hs index ed1bd9bf13..6eb661ac18 100644 --- a/compiler/GHC/ByteCode/Types.hs +++ b/compiler/GHC/ByteCode/Types.hs @@ -84,7 +84,6 @@ newtype RegBitmap = RegBitmap { unRegBitmap :: Word32 } {- Note [GHCi TupleInfo] ~~~~~~~~~~~~~~~~~~~~~~~~ - This contains the data we need for passing unboxed tuples between bytecode and native code diff --git a/compiler/GHC/Cmm/CLabel.hs b/compiler/GHC/Cmm/CLabel.hs index fd9f019e04..3acace8be2 100644 --- a/compiler/GHC/Cmm/CLabel.hs +++ b/compiler/GHC/Cmm/CLabel.hs @@ -478,7 +478,7 @@ data IdLabelInfo -- Note [Bytes label]. | BlockInfoTable -- ^ Like LocalInfoTable but for a proc-point block -- instead of a closure entry-point. - -- See Note [Proc-point local block entry-point]. + -- See Note [Proc-point local block entry-points]. deriving (Eq, Ord) @@ -587,7 +587,7 @@ mkBytesLabel name = IdLabel name NoCafRefs Bytes mkBlockInfoTableLabel :: Name -> CafInfo -> CLabel mkBlockInfoTableLabel name c = IdLabel name c BlockInfoTable - -- See Note [Proc-point local block entry-point]. + -- See Note [Proc-point local block entry-points]. -- Constructing Cmm Labels mkDirty_MUT_VAR_Label, @@ -865,7 +865,7 @@ toEntryLbl platform lbl = case lbl of IdLabel n c (ConInfoTable k) -> IdLabel n c (ConEntry k) IdLabel n _ BlockInfoTable -> mkLocalBlockLabel (nameUnique n) - -- See Note [Proc-point local block entry-point]. + -- See Note [Proc-point local block entry-points]. IdLabel n c _ -> IdLabel n c Entry CmmLabel m ext str CmmInfo -> CmmLabel m ext str CmmEntry CmmLabel m ext str CmmRetInfo -> CmmLabel m ext str CmmRet @@ -898,7 +898,6 @@ hasCAF _ = False -- Note [ticky for LNE] -- ~~~~~~~~~~~~~~~~~~~~~ - -- Until 14 Feb 2013, every ticky counter was associated with a -- closure. Thus, ticky labels used IdLabel. It is odd that -- GHC.Cmm.Info.Build.cafTransfers would consider such a ticky label @@ -1465,7 +1464,6 @@ pprCLabel !platform !sty lbl = -- see Note [Bangs in CLabel] -- Note [Internal proc labels] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Some tools (e.g. the `perf` utility on Linux) rely on the symbol table -- for resolution of function names. To help these tools we provide the -- (enabled by default) -fexpose-all-symbols flag which causes GHC to produce diff --git a/compiler/GHC/Cmm/ContFlowOpt.hs b/compiler/GHC/Cmm/ContFlowOpt.hs index 73c13d2040..350f94c818 100644 --- a/compiler/GHC/Cmm/ContFlowOpt.hs +++ b/compiler/GHC/Cmm/ContFlowOpt.hs @@ -29,7 +29,6 @@ import Control.Monad -- Note [What is shortcutting] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Consider this Cmm code: -- -- L1: ... @@ -53,7 +52,6 @@ import Control.Monad -- Note [Control-flow optimisations] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- This optimisation does three things: -- -- - If a block finishes in an unconditional branch to another block @@ -80,7 +78,6 @@ import Control.Monad -- Note [Shortcut call returns] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- We are going to maintain the "current" graph (LabelMap CmmBlock) as -- we go, and also a mapping from BlockId to BlockId, representing -- continuation labels that we have renamed. This latter mapping is @@ -106,7 +103,6 @@ import Control.Monad -- Note [Shortcut call returns and proc-points] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Consider this code that you might get from a recursive -- let-no-escape: -- diff --git a/compiler/GHC/Cmm/Dataflow.hs b/compiler/GHC/Cmm/Dataflow.hs index 3e310fefcb..ad1c37ace2 100644 --- a/compiler/GHC/Cmm/Dataflow.hs +++ b/compiler/GHC/Cmm/Dataflow.hs @@ -294,7 +294,7 @@ sortBlocks direction entry blockmap = fwd = revPostorderFrom blockmap entry -- Note [Backward vs forward analysis] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The forward and backward cases are not dual. In the forward case, the entry -- points are known, and one simply traverses the body blocks from those points. -- In the backward case, something is known about the exit points, but a @@ -350,7 +350,7 @@ updateFact updateFact fact_join dep_blocks (todo, fbase) lbl new_fact = case lookupFact lbl fbase of Nothing -> - -- Note [No old fact] + -- See Note [No old fact] let !z = mapInsert lbl new_fact fbase in (changed, z) Just old_fact -> case fact_join (OldFact old_fact) (NewFact new_fact) of @@ -362,7 +362,7 @@ updateFact fact_join dep_blocks (todo, fbase) lbl new_fact {- Note [No old fact] - +~~~~~~~~~~~~~~~~~~ We know that the new_fact is >= _|_, so we don't need to join. However, if the new fact is also _|_, and we have already analysed its block, we don't need to record a change. So there's a tradeoff here. It turns diff --git a/compiler/GHC/Cmm/Expr.hs b/compiler/GHC/Cmm/Expr.hs index 52cb63c901..f63ef62dab 100644 --- a/compiler/GHC/Cmm/Expr.hs +++ b/compiler/GHC/Cmm/Expr.hs @@ -86,7 +86,7 @@ data CmmReg data Area = Old -- See Note [Old Area] | Young {-# UNPACK #-} !BlockId -- Invariant: must be a continuation BlockId - -- See Note [Continuation BlockId] in GHC.Cmm.Node. + -- See Note [Continuation BlockIds] in GHC.Cmm.Node. deriving (Eq, Ord, Show) {- Note [Old Area] @@ -203,7 +203,7 @@ data CmmLit | CmmBlock {-# UNPACK #-} !BlockId -- Code label -- Invariant: must be a continuation BlockId - -- See Note [Continuation BlockId] in GHC.Cmm.Node. + -- See Note [Continuation BlockIds] in GHC.Cmm.Node. | CmmHighStackMark -- A late-bound constant that stands for the max -- #bytes of stack space used during a procedure. @@ -410,7 +410,7 @@ data VGcPtr = VGcPtr | VNonGcPtr deriving( Eq, Show ) ----------------------------------------------------------------------------- {- Note [Overlapping global registers] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The backend might not faithfully implement the abstraction of the STG machine with independent registers for different values of type GlobalReg. Specifically, certain pairs of registers (r1, r2) may diff --git a/compiler/GHC/Cmm/Graph.hs b/compiler/GHC/Cmm/Graph.hs index ef8ae7f26b..ff9391a7fe 100644 --- a/compiler/GHC/Cmm/Graph.hs +++ b/compiler/GHC/Cmm/Graph.hs @@ -425,7 +425,7 @@ copyOutOflow profile conv transfer area actuals updfr_off extra_stack_stuff -- Note [Width of parameters] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Consider passing a small (< word width) primitive like Int8# to a function. -- It's actually non-trivial to do this without extending/narrowing: -- * Global registers are considered to have native word width (i.e., 64-bits on diff --git a/compiler/GHC/Cmm/Info/Build.hs b/compiler/GHC/Cmm/Info/Build.hs index 01f3c2a3ff..571a1faae7 100644 --- a/compiler/GHC/Cmm/Info/Build.hs +++ b/compiler/GHC/Cmm/Info/Build.hs @@ -55,7 +55,6 @@ import GHC.Types.Name.Set {- Note [SRTs] ~~~~~~~~~~~ - SRTs are the mechanism by which the garbage collector can determine the live CAFs in the program. @@ -925,7 +924,7 @@ doSCC cfg staticFuns static_data (CyclicSCC nodes) = do {- Note [recursive SRTs] - + ~~~~~~~~~~~~~~~~~~~~~ If the dependency analyser has found us a recursive group of declarations, then we build a single SRT for the whole group, on the grounds that everything in the group is reachable from everything diff --git a/compiler/GHC/Cmm/LayoutStack.hs b/compiler/GHC/Cmm/LayoutStack.hs index ad13e8f431..1bd00ed65a 100644 --- a/compiler/GHC/Cmm/LayoutStack.hs +++ b/compiler/GHC/Cmm/LayoutStack.hs @@ -39,7 +39,7 @@ import Data.Array as Array import Data.List (nub) {- Note [Stack Layout] - + ~~~~~~~~~~~~~~~~~~~ The job of this pass is to - replace references to abstract stack Areas with fixed offsets from Sp. @@ -141,7 +141,7 @@ Pass 2: Note [Two pass approach] - +~~~~~~~~~~~~~~~~~~~~~~~~ The main reason for Pass 2 is being able to insert only the reloads that are needed and the fact that the two passes need different liveness information. Let's consider an example: @@ -510,7 +510,7 @@ handleLastNode cfg procpoints liveness cont_info stackmaps , LabelMap StackMap ) handleBranches - -- Note [diamond proc point] + -- See Note [diamond proc point] | Just l <- futureContinuation middle , (nub $ filter (`setMember` procpoints) $ successors last) == [l] = do @@ -644,9 +644,8 @@ setupStackFrame platform lbl liveness updfr_off ret_args stack0 } --- ----------------------------------------------------------------------------- -- Note [diamond proc point] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~ -- This special case looks for the pattern we get from a typical -- tagged case expression: -- @@ -895,7 +894,7 @@ maybeAddSpAdj cfg sp0 sp_off block = where sp_unwind = CmmRegOff spReg (sp0 - platformWordSizeInBytes platform - sp_off) {- Note [SP old/young offsets] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sp(L) is the Sp offset on entry to block L relative to the base of the OLD area. @@ -1098,7 +1097,7 @@ insertReloads platform stackmap live = {- Note [Lower safe foreign calls] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We start with Sp[young(L1)] = L1 diff --git a/compiler/GHC/Cmm/MachOp.hs b/compiler/GHC/Cmm/MachOp.hs index cd2d331a58..0bd3ac1111 100644 --- a/compiler/GHC/Cmm/MachOp.hs +++ b/compiler/GHC/Cmm/MachOp.hs @@ -340,9 +340,8 @@ isFloatComparison mop = MO_F_Lt {} -> True _other -> False --- ----------------------------------------------------------------------------- --- Inverting conditions - +-- Note [Inverting conditions] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Sometimes it's useful to be able to invert the sense of a -- condition. Not all conditional tests are invertible: in -- particular, floating point conditionals cannot be inverted, because diff --git a/compiler/GHC/Cmm/Node.hs b/compiler/GHC/Cmm/Node.hs index fe6eac3223..d7d35a8bfc 100644 --- a/compiler/GHC/Cmm/Node.hs +++ b/compiler/GHC/Cmm/Node.hs @@ -105,7 +105,7 @@ data CmmNode e x where CmmSwitch :: CmmExpr -- Scrutinee, of some integral type - -> SwitchTargets -- Cases. See [Note SwitchTargets] + -> SwitchTargets -- Cases. See Note [SwitchTargets] -> CmmNode O C CmmCall :: { -- A native call or tail call @@ -114,7 +114,9 @@ data CmmNode e x where cml_cont :: Maybe Label, -- Label of continuation (Nothing for return or tail call) -- - -- Note [Continuation BlockIds]: these BlockIds are called + -- Note [Continuation BlockIds] + -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + -- These BlockIds are called -- Continuation BlockIds, and are the only BlockIds that can -- occur in CmmExprs, namely as (CmmLit (CmmBlock b)) or -- (CmmStackSlot (Young b) _). @@ -196,7 +198,6 @@ sequence. {- Note [Unsafe foreign calls clobber caller-save registers] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - A foreign call is defined to clobber any GlobalRegs that are mapped to caller-saves machine registers (according to the prevailing C ABI). GHC.StgToCmm.Utils.callerSaves tells you which GlobalRegs are caller-saves. @@ -386,7 +387,6 @@ instance DefinerOfRegs GlobalReg (CmmNode e x) where -- Note [Safe foreign calls clobber STG registers] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- During stack layout phase every safe foreign call is expanded into a block -- that contains unsafe foreign call (instead of safe foreign call) and ends -- with a normal call (See Note [Foreign calls]). This means that we must @@ -642,8 +642,8 @@ data CmmTickScope -- the new block could have a combined tick scope a/c+b/d, which -- both tick<2> and tick<3> apply to. --- Note [CmmTick scoping details]: --- +-- Note [CmmTick scoping details] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The scope of a @CmmTick@ is given by the @CmmEntry@ node of the -- same block. Note that as a result of this, optimisations making -- tick scopes more specific can *reduce* the amount of code a tick diff --git a/compiler/GHC/Cmm/Parser.y b/compiler/GHC/Cmm/Parser.y index ed9492aa32..68d5821309 100644 --- a/compiler/GHC/Cmm/Parser.y +++ b/compiler/GHC/Cmm/Parser.y @@ -6,9 +6,9 @@ -- ----------------------------------------------------------------------------- -{- ----------------------------------------------------------------------------- +{- Note [Syntax of .cmm files] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~ NOTE: You are very much on your own in .cmm. There is very little error checking at all: diff --git a/compiler/GHC/Cmm/Pipeline.hs b/compiler/GHC/Cmm/Pipeline.hs index 270a281461..585606fcb2 100644 --- a/compiler/GHC/Cmm/Pipeline.hs +++ b/compiler/GHC/Cmm/Pipeline.hs @@ -175,7 +175,6 @@ cpsTop logger platform cfg proc = -- Note [Sinking after stack layout] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- In the past we considered running sinking pass also before stack -- layout, but after making some measurements we realized that: -- @@ -301,7 +300,7 @@ cpsTop logger platform cfg proc = -- {- Note [inconsistent-pic-reg] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ On x86/Darwin, PIC is implemented by inserting a sequence like call 1f @@ -329,7 +328,7 @@ _GLOBAL_OFFSET_TABLE_, regardless of which entry point we arrived via. -} {- Note [unreachable blocks] - + ~~~~~~~~~~~~~~~~~~~~~~~~~ The control-flow optimiser sometimes leaves unreachable blocks behind containing junk code. These aren't necessarily a problem, but removing them is good because it might save time in the native code diff --git a/compiler/GHC/Cmm/ProcPoint.hs b/compiler/GHC/Cmm/ProcPoint.hs index 0cabea1536..cd55b4d255 100644 --- a/compiler/GHC/Cmm/ProcPoint.hs +++ b/compiler/GHC/Cmm/ProcPoint.hs @@ -428,7 +428,7 @@ attachContInfoTables _ other_decl {- Note [Direct reachability] - +~~~~~~~~~~~~~~~~~~~~~~~~~~ Block B is directly reachable from proc point P iff control can flow from P to B without passing through an intervening proc point. -} @@ -437,7 +437,7 @@ from P to B without passing through an intervening proc point. {- Note [No simple dataflow] - +~~~~~~~~~~~~~~~~~~~~~~~~~ Sadly, it seems impossible to compute the proc points using a single dataflow pass. One might attempt to use this simple lattice: diff --git a/compiler/GHC/Cmm/Sink.hs b/compiler/GHC/Cmm/Sink.hs index 7d90967132..0f3d979716 100644 --- a/compiler/GHC/Cmm/Sink.hs +++ b/compiler/GHC/Cmm/Sink.hs @@ -472,7 +472,7 @@ tryToInline platform liveAfter node assigs = go usages live node skipped (a@(l,rhs,_) : rest) | cannot_inline = dont_inline - | occurs_none = discard -- Note [discard during inlining] + | occurs_none = discard -- See Note [discard during inlining] | occurs_once = inline_and_discard | isTrivial platform rhs = inline_and_keep | otherwise = dont_inline @@ -496,7 +496,7 @@ tryToInline platform liveAfter node assigs = live' = inline foldLocalRegsUsed platform (\m r -> insertLRegSet r m) live rhs - cannot_inline = skipped `regsUsedIn` rhs -- Note [dependent assignments] + cannot_inline = skipped `regsUsedIn` rhs -- See Note [dependent assignments] || l `elemLRegSet` skipped || not (okToInline platform rhs node) @@ -519,8 +519,7 @@ tryToInline platform liveAfter node assigs = inl_exp other = other {- Note [Keeping assignemnts mentioned in skipped RHSs] - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If we have to assignments: [z = y, y = e1] and we skip z we *must* retain the assignment y = e1. This is because we might inline "z = y" into another node later on so we @@ -541,7 +540,7 @@ tryToInline platform liveAfter node assigs = -} {- Note [improveConditional] - + ~~~~~~~~~~~~~~~~~~~~~~~~~ cmmMachOpFold tries to simplify conditionals to turn things like (a == b) != 1 into @@ -579,7 +578,6 @@ improveConditional other = other -- Note [dependent assignments] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- If our assignment list looks like -- -- [ y = e, x = ... y ... ] @@ -690,7 +688,6 @@ conflicts platform (r, rhs, addr) node {- Note [Inlining foldRegsDefd] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - foldRegsDefd is, after optimization, *not* a small function so it's only marked INLINEABLE, but not INLINE. @@ -720,7 +717,6 @@ localRegistersConflict platform expr node = -- Note [Sinking and calls] -- ~~~~~~~~~~~~~~~~~~~~~~~~ --- -- We have three kinds of calls: normal (CmmCall), safe foreign (CmmForeignCall) -- and unsafe foreign (CmmUnsafeForeignCall). We perform sinking pass after -- stack layout (see Note [Sinking after stack layout]) which leads to two @@ -803,7 +799,6 @@ data AbsMem -- Note [Foreign calls clobber heap] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- It is tempting to say that foreign calls clobber only -- non-heap/stack memory, but unfortunately we break this invariant in -- the RTS. For example, in stg_catch_retry_frame we call diff --git a/compiler/GHC/Cmm/Switch.hs b/compiler/GHC/Cmm/Switch.hs index 7bef1e293a..f8c6c674ef 100644 --- a/compiler/GHC/Cmm/Switch.hs +++ b/compiler/GHC/Cmm/Switch.hs @@ -26,7 +26,6 @@ import qualified Data.Map as M -- Note [Cmm Switches, the general plan] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Compiling a high-level switch statement, as it comes out of a STG case -- expression, for example, allows for a surprising amount of design decisions. -- Therefore, we cleanly separated this from the Stg → Cmm transformation, as @@ -51,10 +50,9 @@ import qualified Data.Map as M -- See Note [GHC.Cmm.Switch vs. GHC.Cmm.Switch.Implement] why the two module are -- separated. ------------------------------------------------------------------------------ + -- Note [Magic Constants in GHC.Cmm.Switch] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- There are a lot of heuristics here that depend on magic values where it is -- hard to determine the "best" value (for whatever that means). These are the -- magic values: @@ -83,7 +81,6 @@ minJumpTableOffset = 2 -- Note [SwitchTargets] -- ~~~~~~~~~~~~~~~~~~~~ --- -- The branches of a switch are stored in a SwitchTargets, which consists of an -- (optional) default jump target, and a map from values to jump targets. -- @@ -175,7 +172,6 @@ switchTargetsToTable (SwitchTargets _ (lo,hi) mbdef branches) -- Note [Jump Table Offset] -- ~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Usually, the code for a jump table starting at x will first subtract x from -- the value, to avoid a large amount of empty entries. But if x is very small, -- the extra entries are no worse than the subtraction in terms of code size, and @@ -239,7 +235,6 @@ data SwitchPlan -- -- Note [createSwitchPlan] -- ~~~~~~~~~~~~~~~~~~~~~~~ --- -- A SwitchPlan describes how a Switch statement is to be broken down into -- smaller pieces suitable for code generation. -- diff --git a/compiler/GHC/Cmm/Switch/Implement.hs b/compiler/GHC/Cmm/Switch/Implement.hs index 87dfc1cdaa..30265dc234 100644 --- a/compiler/GHC/Cmm/Switch/Implement.hs +++ b/compiler/GHC/Cmm/Switch/Implement.hs @@ -57,16 +57,15 @@ visitSwitches platform block -- Note [Floating switch expressions] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- When we translate a sparse switch into a search tree we would like -- to compute the value we compare against only once. - +-- -- For this purpose we assign the switch expression to a local register -- and then use this register when constructing the actual binary tree. - +-- -- This is important as the expression could contain expensive code like -- memory loads or divisions which we REALLY don't want to duplicate. - +-- -- This happened in parts of the handwritten RTS Cmm code. See also #16933 -- See Note [Floating switch expressions] diff --git a/compiler/GHC/CmmToAsm.hs b/compiler/GHC/CmmToAsm.hs index e7a392d822..88c72f6b16 100644 --- a/compiler/GHC/CmmToAsm.hs +++ b/compiler/GHC/CmmToAsm.hs @@ -192,7 +192,6 @@ data NativeGenAcc statics instr {- Note [Unwinding information in the NCG] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Unwind information is a type of metadata which allows a debugging tool to reconstruct the values of machine registers at the time a procedure was entered. For the most part, the production of unwind information is handled by diff --git a/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs b/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs index 65872c73be..2698e6f17f 100644 --- a/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs +++ b/compiler/GHC/CmmToAsm/AArch64/CodeGen.hs @@ -62,6 +62,7 @@ import GHC.Utils.Misc import GHC.Utils.Panic -- Note [General layout of an NCG] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- @cmmTopCodeGen@ will be our main entry point to code gen. Here we'll get -- @RawCmmDecl@; see GHC.Cmm -- @@ -846,7 +847,7 @@ getRegister' config plat expr MO_Sub w -> intOp False w (\d x y -> unitOL $ annExpr expr (SUB d x y)) -- Note [CSET] - -- + -- ~~~~~~~~~~~ -- Setting conditional flags: the architecture internally knows the -- following flag bits. And based on thsoe comparisons as in the -- table below. diff --git a/compiler/GHC/CmmToAsm/AArch64/Ppr.hs b/compiler/GHC/CmmToAsm/AArch64/Ppr.hs index 8d93a56395..5a48241c0b 100644 --- a/compiler/GHC/CmmToAsm/AArch64/Ppr.hs +++ b/compiler/GHC/CmmToAsm/AArch64/Ppr.hs @@ -147,7 +147,7 @@ pprBasicBlock config info_env (BasicBlock blockid instrs) then ppr (mkAsmTempEndLabel info_lbl) <> char ':' else empty) -- Make sure the info table has the right .loc for the block - -- coming right after it. See [Note: Info Offset] + -- coming right after it. See Note [Info Offset] infoTableLoc = case instrs of (l@LOCATION{} : _) -> pprInstr platform l _other -> empty @@ -187,11 +187,12 @@ pprGloblDecl platform lbl | otherwise = text "\t.globl " <> pdoc platform lbl -- Note [Always use objects for info tables] --- See discussion in X86.Ppr --- for why this is necessary. Essentially we need to ensure that we never --- pass function symbols when we migth want to lookup the info table. If we --- did, we could end up with procedure linking tables (PLT)s, and thus the --- lookup wouldn't point to the function, but into the jump table. +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-- See discussion in X86.Ppr for why this is necessary. Essentially we need to +-- ensure that we never pass function symbols when we migth want to lookup the +-- info table. If we did, we could end up with procedure linking tables +-- (PLT)s, and thus the lookup wouldn't point to the function, but into the +-- jump table. -- -- Fun fact: The LLVMMangler exists to patch this issue su on the LLVM side as -- well. diff --git a/compiler/GHC/CmmToAsm/BlockLayout.hs b/compiler/GHC/CmmToAsm/BlockLayout.hs index 70e131c717..747702658e 100644 --- a/compiler/GHC/CmmToAsm/BlockLayout.hs +++ b/compiler/GHC/CmmToAsm/BlockLayout.hs @@ -67,10 +67,9 @@ import GHC.Data.UnionFind * Feed this CFG into the block layout code (`sequenceTop`) in this module. Which will then produce a code layout based on the input weights. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~~~ Note [Chain based CFG serialization] - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Note [Chain based CFG serialization] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For additional information also look at https://gitlab.haskell.org/ghc/ghc/wikis/commentary/compiler/code-layout @@ -189,10 +188,9 @@ import GHC.Data.UnionFind While E does not follow X it's still beneficial to place them near each other. This can be advantageous if eg C,X,E will end up in the same cache line. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~~~ Note [Triangle Control Flow] - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Note [Triangle Control Flow] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checking if an argument is already evaluated leads to a somewhat special case which looks like this: @@ -240,10 +238,9 @@ import GHC.Data.UnionFind Assuming that Lwork is large the chance that the "call" ends up in the same cache line is also fairly small. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~~~ Note [Layout relevant edge weights] - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Note [Layout relevant edge weights] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The input to the chain based code layout algorithm is a CFG with edges annotated with their frequency. The frequency of traversal corresponds quite well to the cost of not placing @@ -373,9 +370,9 @@ takeL :: Int -> BlockChain -> [BlockId] takeL n (BlockChain blks) = take n . fromOL $ blks + -- Note [Combining neighborhood chains] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- See also Note [Chain based CFG serialization] -- We have the chains (A-B-C-D) and (E-F) and an Edge C->E. -- diff --git a/compiler/GHC/CmmToAsm/CFG.hs b/compiler/GHC/CmmToAsm/CFG.hs index 58041fef2c..0a662d7ff9 100644 --- a/compiler/GHC/CmmToAsm/CFG.hs +++ b/compiler/GHC/CmmToAsm/CFG.hs @@ -150,7 +150,7 @@ instance Outputable CfgEdge where -- or has it been introduced during assembly codegen. We use this to maintain -- some information which would otherwise be lost during the -- Cmm \<-> asm transition. --- See also Note [Inverting Conditional Branches] +-- See also Note [Inverting conditions] data TransitionSource = CmmSource { trans_cmmNode :: (CmmNode O C) , trans_info :: BranchInfo } @@ -248,7 +248,7 @@ filterEdges f cfg = {- Note [Updating the CFG during shortcutting] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See Note [What is shortcutting] in the control flow optimization code (GHC.Cmm.ContFlowOpt) for a slightly more in depth explanation on shortcutting. @@ -1013,7 +1013,6 @@ mkGlobalWeights root localCfg {- Note [Static Branch Prediction] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The work here has been based on the paper "Static Branch Prediction and Program Profile Analysis" by Y Wu, JR Larus. diff --git a/compiler/GHC/CmmToAsm/Dwarf.hs b/compiler/GHC/CmmToAsm/Dwarf.hs index fcff4be74e..07ca55d6d8 100644 --- a/compiler/GHC/CmmToAsm/Dwarf.hs +++ b/compiler/GHC/CmmToAsm/Dwarf.hs @@ -148,7 +148,7 @@ debugSplitProcs b = concat $ H.mapElems $ mergeMaps $ map (split Nothing) b {- Note [Splitting DebugBlocks] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DWARF requires that we break up the nested DebugBlocks produced from the C-- AST. For instance, we begin with tick trees containing nested procs. For example, diff --git a/compiler/GHC/CmmToAsm/Dwarf/Types.hs b/compiler/GHC/CmmToAsm/Dwarf/Types.hs index f8f0ae5c44..e29f03e1d6 100644 --- a/compiler/GHC/CmmToAsm/Dwarf/Types.hs +++ b/compiler/GHC/CmmToAsm/Dwarf/Types.hs @@ -257,7 +257,7 @@ pprDwarfARanges platform arngs unitU = pprDwarfARange :: Platform -> DwarfARange -> SDoc pprDwarfARange platform arng = - -- Offset due to Note [Info offset]. + -- Offset due to Note [Info Offset]. pprWord platform (pdoc platform (dwArngStartLabel arng) <> text "-1") $$ pprWord platform length where @@ -410,7 +410,6 @@ pprFrameBlock platform (DwarfFrameBlock hasInfo uws0) = -- Note [Info Offset] -- ~~~~~~~~~~~~~~~~~~ --- -- GDB was pretty much written with C-like programs in mind, and as a -- result they assume that once you have a return address, it is a -- good idea to look at (PC-1) to unwind further - as that's where the diff --git a/compiler/GHC/CmmToAsm/PPC/CodeGen.hs b/compiler/GHC/CmmToAsm/PPC/CodeGen.hs index 2184c0fc29..cd88a9f078 100644 --- a/compiler/GHC/CmmToAsm/PPC/CodeGen.hs +++ b/compiler/GHC/CmmToAsm/PPC/CodeGen.hs @@ -738,6 +738,7 @@ temporary, then do the other computation, and then use the temporary: -} {- Note [Power instruction format] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In some instructions the 16 bit offset must be a multiple of 4, i.e. the two least significant bits must be zero. The "Power ISA" specification calls these instruction formats "DS-FORM" and the instructions with @@ -1210,6 +1211,7 @@ genCCall (PrimTarget (MO_AtomicRead width)) [dst] [addr] ] -- Note [Seemingly useless cmp and bne] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- In Power ISA, Book II, Section 4.4.1, Instruction Synchronize Instruction -- the second paragraph says that isync may complete before storage accesses -- "associated" with a preceding instruction have been performed. The cmp @@ -2535,12 +2537,14 @@ coerceFP2Int' (ArchPPC_64 _) _ toRep x = do coerceFP2Int' _ _ _ _ = panic "PPC.CodeGen.coerceFP2Int: unknown arch" -- Note [.LCTOC1 in PPC PIC code] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The .LCTOC1 label is defined to point 32768 bytes into the GOT table -- to make the most of the PPC's 16-bit displacements. -- As 16-bit signed offset is used (usually via addi/lwz instructions) -- first element will have '-32768' offset against .LCTOC1. -- Note [implicit register in PPC PIC code] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- PPC generates calls by labels in assembly -- in form of: -- bl puts+32768@plt diff --git a/compiler/GHC/CmmToAsm/Reg/Utils.hs b/compiler/GHC/CmmToAsm/Reg/Utils.hs index 3a832963fe..0a6bfabdbd 100644 --- a/compiler/GHC/CmmToAsm/Reg/Utils.hs +++ b/compiler/GHC/CmmToAsm/Reg/Utils.hs @@ -4,7 +4,6 @@ where {- Note [UniqFM and the register allocator] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Before UniqFM had a key type the register allocator wasn't picky about key types, using VirtualReg, Reg and Unique at various use sites for the same map. diff --git a/compiler/GHC/CmmToAsm/X86/CodeGen.hs b/compiler/GHC/CmmToAsm/X86/CodeGen.hs index 52f2a52123..028887a56f 100644 --- a/compiler/GHC/CmmToAsm/X86/CodeGen.hs +++ b/compiler/GHC/CmmToAsm/X86/CodeGen.hs @@ -129,7 +129,6 @@ cmmTopCodeGen (CmmData sec dat) = {- Note [Verifying basic blocks] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We want to guarantee a few things about the results of instruction selection. @@ -231,7 +230,6 @@ addSpUnwindings instr = return $ unitOL instr {- Note [Keeping track of the current block] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - When generating instructions for Cmm we sometimes require the current block for things like retry loops. @@ -2906,7 +2904,7 @@ evalArgs bid actuals newLocalReg ty = LocalReg <$> getUniqueM <*> pure ty -- Note [DIV/IDIV for bytes] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~ -- IDIV reminder: -- Size Dividend Divisor Quotient Remainder -- byte %ax r/m8 %al %ah @@ -2990,7 +2988,7 @@ genCCall32' target dest_regs args = do let -- Align stack to 16n for calls, assuming a starting stack -- alignment of 16n - word_size on procedure entry. Which we - -- maintiain. See Note [rts/StgCRun.c : Stack Alignment on X86] + -- maintiain. See Note [Stack Alignment on X86] in rts/StgCRun.c. sizes = map (arg_size_bytes . cmmExprType platform) (reverse args) raw_arg_size = sum sizes + platformWordSizeInBytes platform arg_pad_size = (roundTo 16 $ raw_arg_size) - raw_arg_size @@ -3605,10 +3603,8 @@ condIntReg cond x y = do return (Any II32 code) ------------------------------------------------------------ ---- Note [SSE Parity Checks] --- ------------------------------------------------------------ - +-- Note [SSE Parity Checks] +-- ~~~~~~~~~~~~~~~~~~~~~~~~ -- We have to worry about unordered operands (eg. comparisons -- against NaN). If the operands are unordered, the comparison -- sets the parity flag, carry flag and zero flag. diff --git a/compiler/GHC/CmmToAsm/X86/Instr.hs b/compiler/GHC/CmmToAsm/X86/Instr.hs index 947a25b2d8..1f1515b0c9 100644 --- a/compiler/GHC/CmmToAsm/X86/Instr.hs +++ b/compiler/GHC/CmmToAsm/X86/Instr.hs @@ -120,7 +120,7 @@ Hence GLDZ and GLD1. Bwahahahahahahaha! {- Note [x86 Floating point precision] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Intel's internal floating point registers are by default 80 bit extended precision. This means that all operations done on values in registers are done at 80 bits, and unless the intermediate values are @@ -795,6 +795,8 @@ mkJumpInstr id = [JXX ALWAYS id] -- Note [Windows stack layout] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + -- | On most OSes the kernel will place a guard page after the current stack -- page. If you allocate larger than a page worth you may jump over this -- guard page. Not only is this a security issue, but on certain OSes such @@ -896,9 +898,8 @@ mkStackDeallocInstr platform amount _ -> panic "X86.mkStackDeallocInstr" --- -- Note [extra spill slots] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~ -- If the register allocator used more spill slots than we have -- pre-allocated (rESERVED_C_STACK_BYTES), then we must allocate more -- C stack space on entry and exit from this proc. Therefore we diff --git a/compiler/GHC/CmmToAsm/X86/Ppr.hs b/compiler/GHC/CmmToAsm/X86/Ppr.hs index 15e1b961df..49b6988c1d 100644 --- a/compiler/GHC/CmmToAsm/X86/Ppr.hs +++ b/compiler/GHC/CmmToAsm/X86/Ppr.hs @@ -48,12 +48,8 @@ import GHC.Utils.Panic import Data.Word --- ----------------------------------------------------------------------------- --- Printing this stuff out --- --- -- Note [Subsections Via Symbols] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- If we are using the .subsections_via_symbols directive -- (available on recent versions of Darwin), -- we have to make sure that there is some kind of reference @@ -163,7 +159,7 @@ pprBasicBlock config info_env (BasicBlock blockid instrs) ppWhen (ncgDwarfEnabled config) (pdoc platform (mkAsmTempEndLabel infoLbl) <> colon) -- Make sure the info table has the right .loc for the block - -- coming right after it. See [Note: Info Offset] + -- coming right after it. See Note [Info Offset] infoTableLoc = case instrs of (l@LOCATION{} : _) -> pprInstr platform l _other -> empty diff --git a/compiler/GHC/CmmToC.hs b/compiler/GHC/CmmToC.hs index 6528f63921..a6a036c290 100644 --- a/compiler/GHC/CmmToC.hs +++ b/compiler/GHC/CmmToC.hs @@ -167,6 +167,7 @@ pprAlignment words = text "__attribute__((aligned(" <> int (widthInBytes words) <> text ")))" -- Note [StgWord alignment] +-- ~~~~~~~~~~~~~~~~~~~~~~~~ -- C codegen builds static closures as StgWord C arrays (pprWordArray). -- Their real C type is 'StgClosure'. Macros like UNTAG_CLOSURE assume -- pointers to 'StgClosure' are aligned at pointer size boundary: diff --git a/compiler/GHC/CmmToLlvm/Base.hs b/compiler/GHC/CmmToLlvm/Base.hs index b209c4cd67..cc4377240b 100644 --- a/compiler/GHC/CmmToLlvm/Base.hs +++ b/compiler/GHC/CmmToLlvm/Base.hs @@ -591,7 +591,7 @@ aliasify (LMGlobal var val) = do ] -- Note [Llvm Forward References] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The issue here is that LLVM insists on being strongly typed at -- every corner, so the first time we mention something, we have to -- settle what type we assign to it. That makes things awkward, as Cmm diff --git a/compiler/GHC/CmmToLlvm/CodeGen.hs b/compiler/GHC/CmmToLlvm/CodeGen.hs index 9e20b65a80..a57a6f79f0 100644 --- a/compiler/GHC/CmmToLlvm/CodeGen.hs +++ b/compiler/GHC/CmmToLlvm/CodeGen.hs @@ -1255,7 +1255,6 @@ genExpectLit expLit expTy var = do {- Note [Literals and branch conditions] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - It is important that whenever we generate branch conditions for literals like '1', they are properly narrowed to an LLVM expression of type 'i1' (for bools.) Otherwise, nobody is happy. So when we convert diff --git a/compiler/GHC/Core/Coercion.hs b/compiler/GHC/Core/Coercion.hs index 6f5c1ac338..ef6d4af5ec 100644 --- a/compiler/GHC/Core/Coercion.hs +++ b/compiler/GHC/Core/Coercion.hs @@ -843,7 +843,7 @@ mkAppCos :: Coercion mkAppCos co1 cos = foldl' mkAppCo co1 cos {- Note [Unused coercion variable in ForAllCo] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See Note [Unused coercion variable in ForAllTy] in GHC.Core.TyCo.Rep for the motivation for checking coercion variable in types. To lift the design choice to (ForAllCo cv kind_co body_co), we have two options: @@ -2117,7 +2117,7 @@ liftCoSubstTyVar (LC subst env) r v = Just $ mkReflCo r (substTyVar subst v) {- Note [liftCoSubstVarBndr] - + ~~~~~~~~~~~~~~~~~~~~~~~~~ callback: 'liftCoSubstVarBndrUsing' needs to be general enough to work in two situations: diff --git a/compiler/GHC/Core/FamInstEnv.hs b/compiler/GHC/Core/FamInstEnv.hs index c1715cc270..c0981ac9e1 100644 --- a/compiler/GHC/Core/FamInstEnv.hs +++ b/compiler/GHC/Core/FamInstEnv.hs @@ -815,7 +815,7 @@ lookupFamInstEnvConflicts envs fam_inst@(FamInst { fi_axiom = new_axiom }) if compatibleBranches (coAxiomSingleBranch old_axiom) new_branch then Nothing else Just noSubst - -- Note [Family instance overlap conflicts] + -- See Note [Family instance overlap conflicts] noSubst = panic "lookupFamInstEnvConflicts noSubst" new_branch = coAxiomSingleBranch new_axiom @@ -826,7 +826,6 @@ lookupFamInstEnvConflicts envs fam_inst@(FamInst { fi_axiom = new_axiom }) {- Note [Verifying injectivity annotation] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Injectivity means that the RHS of a type family uniquely determines the LHS (see Note [Type inference for type families with injectivity]). The user informs us about injectivity using an injectivity annotation and it is GHC's task to verify that diff --git a/compiler/GHC/Core/InstEnv.hs b/compiler/GHC/Core/InstEnv.hs index 3bb9a32a50..ab23fcae2c 100644 --- a/compiler/GHC/Core/InstEnv.hs +++ b/compiler/GHC/Core/InstEnv.hs @@ -869,7 +869,7 @@ lookupInstEnv' ie vis_mods cls tys -- apply in the future. This covers an instance like C Int and -- a target like [W] C (F a), where F is a type family. SurelyApart -> find ms us rest - -- Note [Infinitary substitution in lookup] + -- See Note [Infinitary substitution in lookup] MaybeApart MARInfinite _ -> find ms us rest _ -> find ms (item:us) rest where diff --git a/compiler/GHC/Core/Lint.hs b/compiler/GHC/Core/Lint.hs index c098afd57c..ec9b024fc5 100644 --- a/compiler/GHC/Core/Lint.hs +++ b/compiler/GHC/Core/Lint.hs @@ -640,8 +640,8 @@ lintLetBind top_lvl rec_flag binder rhs rhs_ty (badBndrTyMsg binder (text "unlifted")) -- Check that if the binder is at the top level and has type Addr#, - -- that it is a string literal, see - -- Note [Core top-level string literals]. + -- that it is a string literal. + -- See Note [Core top-level string literals]. ; checkL (not (isTopLevel top_lvl && binder_ty `eqType` addrPrimTy) || exprIsTickedString rhs) (mkTopNonLitStrMsg binder) @@ -1005,8 +1005,8 @@ lintCoreFun (Var var) nargs = lintIdOcc var nargs lintCoreFun (Lam var body) nargs - -- Act like lintCoreExpr of Lam, but *don't* call markAllJoinsBad; see - -- Note [Beta redexes] + -- Act like lintCoreExpr of Lam, but *don't* call markAllJoinsBad; + -- See Note [Beta redexes] | nargs /= 0 = lintLambda var $ lintCoreFun body (nargs - 1) diff --git a/compiler/GHC/Core/Make.hs b/compiler/GHC/Core/Make.hs index 0ab8a151bc..06cb867c94 100644 --- a/compiler/GHC/Core/Make.hs +++ b/compiler/GHC/Core/Make.hs @@ -836,7 +836,6 @@ tYPE_ERROR_ID = mkRuntimeErrorId typeErrorName -- Note [aBSENT_SUM_FIELD_ERROR_ID] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Unboxed sums are transformed into unboxed tuples in GHC.Stg.Unarise.mkUbxSum -- and fields that can't be reached are filled with rubbish values. It's easy to -- come up with rubbish literal values: we use 0 (ints/words) and 0.0 diff --git a/compiler/GHC/Core/Map/Expr.hs b/compiler/GHC/Core/Map/Expr.hs index 4c79cd880a..60ee2c94b5 100644 --- a/compiler/GHC/Core/Map/Expr.hs +++ b/compiler/GHC/Core/Map/Expr.hs @@ -206,7 +206,6 @@ eqCoreExpr e1 e2 = eqDeBruijnExpr (deBruijnize e1) (deBruijnize e2) {- Note [Alpha-equality for Coercion arguments] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The 'Coercion' constructor only appears in argument positions, and so, if the functions are equal, then the arguments must have equal types. Because the comparison for coercions (correctly) checks only their types, checking for @@ -215,7 +214,6 @@ alpha-equality of the coercions is redundant. {- Note [Alpha-equality for let-bindings] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For /recursive/ let-bindings we need to check that the types of the binders are alpha-equivalent. Otherwise diff --git a/compiler/GHC/Core/Multiplicity.hs b/compiler/GHC/Core/Multiplicity.hs index 2c3828c712..b3c268c356 100644 --- a/compiler/GHC/Core/Multiplicity.hs +++ b/compiler/GHC/Core/Multiplicity.hs @@ -219,7 +219,7 @@ We have The goal is to maximise reuse of types between linear code and traditional code. This is argued at length in the proposal and the article (links in Note -[Linear Types]). +[Linear types]). Note [Polymorphisation of linear fields] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/compiler/GHC/Core/Opt/Arity.hs b/compiler/GHC/Core/Opt/Arity.hs index 9ff08b142b..ceef44afbf 100644 --- a/compiler/GHC/Core/Opt/Arity.hs +++ b/compiler/GHC/Core/Opt/Arity.hs @@ -127,7 +127,7 @@ exprArity e = go e | otherwise = go e go (Tick t e) | not (tickishIsCode t) = go e go (Cast e co) = trim_arity (go e) (coercionRKind co) - -- Note [exprArity invariant] + -- See Note [exprArity invariant] go (App e (Type _)) = go e go (App f a) | exprIsTrivial a = (go f - 1) `max` 0 -- See Note [exprArity for applications] @@ -155,7 +155,7 @@ typeArity ty | Just (tc,tys) <- splitTyConApp_maybe ty , Just (ty', _) <- instNewTyCon_maybe tc tys - , Just rec_nts' <- checkRecTc rec_nts tc -- See Note [Expanding newtypes] + , Just rec_nts' <- checkRecTc rec_nts tc -- See Note [Expanding newtypes and products] -- in GHC.Core.TyCon -- , not (isClassTyCon tc) -- Do not eta-expand through newtype classes -- -- See Note [Newtype classes and eta expansion] @@ -708,7 +708,7 @@ until it finds a stable arity type. Two wrinkles by the 'am_sigs' field in 'FindRhsArity', and 'lookupSigEnv' in the Var case of 'arityType'. -Note [Exciting Arity] +Note [Exciting arity] ~~~~~~~~~~~~~~~~~~~~~ The fixed-point iteration in 'findRhsArity' stabilises very quickly in almost all cases. To get notified of cases where we need an usual number of iterations, @@ -1047,8 +1047,8 @@ arityType env (App fun arg ) -- arityType env (Case scrut bndr _ alts) | exprIsDeadEnd scrut || null alts - = botArityType -- Do not eta expand. See Note [Dealing with bottom (1)] - | not (pedanticBottoms env) -- See Note [Dealing with bottom (2)] + = botArityType -- Do not eta expand. See (1) in Note [Dealing with bottom] + | not (pedanticBottoms env) -- See (2) in Note [Dealing with bottom] , myExprIsCheap env scrut (Just (idType bndr)) = alts_type | exprOkForSpeculation scrut @@ -1514,7 +1514,7 @@ etaInfoApp in_scope expr eis (subst', b') = Core.substBindSC subst b -- Beta-reduction if possible, pushing any intervening casts past - -- the argument. See Note [The EtaInfo mechansim] + -- the argument. See Note [The EtaInfo mechanism] go subst (Lam v e) (EI (b:bs) mco) | Just (arg,mco') <- pushMCoArg mco (varToCoreExpr b) = go (Core.extendSubst subst v arg) e (EI bs mco') diff --git a/compiler/GHC/Core/Opt/CallArity.hs b/compiler/GHC/Core/Opt/CallArity.hs index c551227486..656d6a9fc1 100644 --- a/compiler/GHC/Core/Opt/CallArity.hs +++ b/compiler/GHC/Core/Opt/CallArity.hs @@ -99,7 +99,7 @@ The two analysis are not completely independent, as a higher arity can improve the information about what variables are being called once or multiple times. Note [Analysis I: The arity analysis] ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The arity analysis is quite straightforward: The information about an expression is an @@ -115,7 +115,7 @@ minimum (considering Nothing an infinity). Note [Analysis II: The Co-Called analysis] ------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The second part is more sophisticated. For reasons explained below, it is not sufficient to simply know how often an expression evaluates a variable. Instead @@ -438,7 +438,7 @@ callArityAnalProgram binds = binds' where (_, binds') = callArityTopLvl [] emptyVarSet binds --- See Note [Analysing top-level-binds] +-- See Note [Analysing top-level binds] callArityTopLvl :: [Var] -> VarSet -> [CoreBind] -> (CallArityRes, [CoreBind]) callArityTopLvl exported _ [] = ( calledMultipleTimes $ (emptyUnVarGraph, mkVarEnv $ [(v, 0) | v <- exported]) diff --git a/compiler/GHC/Core/Opt/ConstantFold.hs b/compiler/GHC/Core/Opt/ConstantFold.hs index 8910257477..bb44ed4bd5 100644 --- a/compiler/GHC/Core/Opt/ConstantFold.hs +++ b/compiler/GHC/Core/Opt/ConstantFold.hs @@ -1715,7 +1715,9 @@ guardDoubleDiv = do [Lit (LitDouble d1), Lit (LitDouble d2)] <- getArgs guard $ (d1 /=0 || d2 > 0) -- see Note [negative zero] && d2 /= 0 -- avoid NaN and Infinity/-Infinity --- Note [negative zero] Avoid (0 / -d), otherwise 0/(-1) reduces to +-- Note [negative zero] +-- ~~~~~~~~~~~~~~~~~~~~ +-- Avoid (0 / -d), otherwise 0/(-1) reduces to -- zero, but we might want to preserve the negative zero here which -- is representable in Float/Double but not in (normalised) -- Rational. (#3676) Perhaps we should generate (0 :% (-1)) instead? @@ -1732,14 +1734,12 @@ strengthReduction two_lit add_op = do -- Note [Strength reduction] -- Note [Strength reduction] -- ~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- This rule turns floating point multiplications of the form 2.0 * x and -- x * 2.0 into x + x addition, because addition costs less than multiplication. -- See #7116 -- Note [What's true and false] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- trueValInt and falseValInt represent true and false values returned by -- comparison primops for Char, Int, Word, Integer, Double, Float and Addr. -- True is represented as an unboxed 1# literal, while false is represented @@ -1820,7 +1820,7 @@ tagToEnumRule = do ------------------------------ dataToTagRule :: RuleM CoreExpr --- See Note [dataToTag#] in primops.txt.pp +-- See Note [dataToTag# magic]. dataToTagRule = a `mplus` b where -- dataToTag (tagToEnum x) ==> x @@ -2465,7 +2465,6 @@ match_cstring_length rule_env env _ [lit1] in Just (Lit (mkLitInt (roPlatform rule_env) (fromIntegral len))) match_cstring_length _ _ _ _ = Nothing ---------------------------------------------------- {- Note [inlineId magic] ~~~~~~~~~~~~~~~~~~~~~~~~ The call 'inline f' arranges that 'f' is inlined, regardless of @@ -3306,7 +3305,7 @@ Instead, we deal with turning one branch into DEFAULT in GHC.Core.Opt.Simplify.U Note [caseRules for dataToTag] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See also Note [dataToTag#] in primops.txt.pp +See also Note [dataToTag# magic]. We want to transform case dataToTag x of diff --git a/compiler/GHC/Core/Opt/FloatIn.hs b/compiler/GHC/Core/Opt/FloatIn.hs index 6e4b724310..37cb23e338 100644 --- a/compiler/GHC/Core/Opt/FloatIn.hs +++ b/compiler/GHC/Core/Opt/FloatIn.hs @@ -353,7 +353,7 @@ So: rather than drop \tr{w}'s binding here, we add it onto the list of things to drop in the outer let's body, and let nature take its course. -Note [extra_fvs (1): avoid floating into RHS] +Note [extra_fvs (1)]: avoid floating into RHS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Consider let x=\y....t... in body. We do not necessarily want to float a binding for t into the RHS, because it'll immediately be floated out @@ -371,7 +371,7 @@ can't have unboxed bindings. So we make "extra_fvs" which is the rhs_fvs of such bindings, and arrange to dump bindings that bind extra_fvs before the entire let. -Note [extra_fvs (2): free variables of rules] +Note [extra_fvs (2)]: free variables of rules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Consider let x{rule mentioning y} = rhs in body @@ -504,7 +504,7 @@ fiBind :: Platform fiBind platform to_drop (AnnNonRec id ann_rhs@(rhs_fvs, rhs)) body_fvs = ( extra_binds ++ shared_binds -- Land these before - -- See Note [extra_fvs (1,2)] + -- See Note [extra_fvs (1)] and Note [extra_fvs (2)] , FB (unitDVarSet id) rhs_fvs' -- The new binding itself (FloatLet (NonRec id rhs')) , body_binds ) -- Land these after @@ -512,12 +512,12 @@ fiBind platform to_drop (AnnNonRec id ann_rhs@(rhs_fvs, rhs)) body_fvs where body_fvs2 = body_fvs `delDVarSet` id - rule_fvs = bndrRuleAndUnfoldingVarsDSet id -- See Note [extra_fvs (2): free variables of rules] + rule_fvs = bndrRuleAndUnfoldingVarsDSet id -- See Note [extra_fvs (2)] extra_fvs | noFloatIntoRhs NonRecursive id rhs = rule_fvs `unionDVarSet` rhs_fvs | otherwise = rule_fvs - -- See Note [extra_fvs (1): avoid floating into RHS] + -- See Note [extra_fvs (1)] -- No point in floating in only to float straight out again -- We *can't* float into ok-for-speculation unlifted RHSs -- But do float into join points @@ -601,7 +601,7 @@ noFloatIntoArg expr expr_ty || all isTyVar (bndr:bndrs) -- Wrinkle 1 (b) -- See Note [noFloatInto considerations] wrinkle 2 - | otherwise -- Note [noFloatInto considerations] wrinkle 2 + | otherwise -- See Note [noFloatInto considerations] wrinkle 2 = exprIsTrivial deann_expr || exprIsHNF deann_expr where deann_expr = deAnnotate' expr @@ -742,7 +742,6 @@ sepBindsByDropPoint platform is_case drop_pts floaters {- Note [Duplicating floats] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For case expressions we duplicate the binding if it is reasonably small, and if it is not used in all the RHSs This is good for situations like diff --git a/compiler/GHC/Core/Opt/FloatOut.hs b/compiler/GHC/Core/Opt/FloatOut.hs index fbed53fbf3..1a88c97d55 100644 --- a/compiler/GHC/Core/Opt/FloatOut.hs +++ b/compiler/GHC/Core/Opt/FloatOut.hs @@ -280,7 +280,7 @@ splitRecFloats fs -- non-rec installUnderLambdas :: Bag FloatBind -> CoreExpr -> CoreExpr --- Note [Floating out of Rec rhss] +-- See Note [Floating out of Rec rhss] installUnderLambdas floats e | isEmptyBag floats = e | otherwise = go e @@ -374,7 +374,6 @@ floatBody lvl arg -- Used rec rhss, and case-alternative rhss {- Note [Floating past breakpoints] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We used to disallow floating out of breakpoint ticks (see #10052). However, I think this is too restrictive. @@ -428,7 +427,7 @@ floatExpr (Tick tickish expr) in (fs, annotated_defns, Tick tickish expr') } - -- Note [Floating past breakpoints] + -- See Note [Floating past breakpoints] | Breakpoint{} <- tickish = case (floatExpr expr) of { (fs, floating_defns, expr') -> (fs, floating_defns, Tick tickish expr') } diff --git a/compiler/GHC/Core/Opt/LiberateCase.hs b/compiler/GHC/Core/Opt/LiberateCase.hs index 3c9eb5c3d0..1598526ada 100644 --- a/compiler/GHC/Core/Opt/LiberateCase.hs +++ b/compiler/GHC/Core/Opt/LiberateCase.hs @@ -168,7 +168,7 @@ libCaseBind env (Rec pairs) ok_pair (id,_) = idArity id > 0 -- Note [Only functions!] - && not (isDeadEndId id) -- Note [Not bottoming ids] + && not (isDeadEndId id) -- Note [Not bottoming Ids] {- Note [Not bottoming Ids] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/compiler/GHC/Core/Opt/Simplify.hs b/compiler/GHC/Core/Opt/Simplify.hs index 4f5ece8fca..575512b7c8 100644 --- a/compiler/GHC/Core/Opt/Simplify.hs +++ b/compiler/GHC/Core/Opt/Simplify.hs @@ -1393,6 +1393,7 @@ simplTick env tickish expr cont getDoneId other = pprPanic "getDoneId" (ppr other) -- Note [case-of-scc-of-case] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- It's pretty important to be able to transform case-of-case when -- there's an SCC in the way. For example, the following comes up -- in nofib/real/compress/Encode.hs: @@ -1992,6 +1993,7 @@ simplIdF env var cont cont' = trimJoinCont var mb_join cont in simplExprF env' e cont' -- Note [zapSubstEnv] + -- ~~~~~~~~~~~~~~~~~~ -- The template is already simplified, so don't re-substitute. -- This is VITAL. Consider -- let x = e in diff --git a/compiler/GHC/Core/Opt/Simplify/Utils.hs b/compiler/GHC/Core/Opt/Simplify/Utils.hs index e288646d74..409f3176eb 100644 --- a/compiler/GHC/Core/Opt/Simplify/Utils.hs +++ b/compiler/GHC/Core/Opt/Simplify/Utils.hs @@ -1293,7 +1293,7 @@ preInlineUnconditionally env top_lvl bndr rhs rhs_env | not (one_occ (idOccInfo bndr)) = Nothing | not (isStableUnfolding unf) = Just $! (extend_subst_with rhs) - -- Note [Stable unfoldings and preInlineUnconditionally] + -- See Note [Stable unfoldings and preInlineUnconditionally] | not (isInlinePragma inline_prag) , Just inl <- maybeUnfoldingTemplate unf = Just $! (extend_subst_with inl) | otherwise = Nothing @@ -1395,7 +1395,7 @@ our new view that inlining is like a RULE, so I'm sticking to the 'active' story for now. NB: unconditional inlining of this sort can introduce ticks in places that -may seem surprising; for instance, the LHS of rules. See Note [Simplfying +may seem surprising; for instance, the LHS of rules. See Note [Simplifying rules] for details. -} @@ -2196,7 +2196,7 @@ prepareAlts scrut case_bndr' alts mkCase tries these things -* Note [Nerge nested cases] +* Note [Merge nested cases] * Note [Eliminate identity case] * Note [Scrutinee constant folding] diff --git a/compiler/GHC/Core/Opt/SpecConstr.hs b/compiler/GHC/Core/Opt/SpecConstr.hs index 9c4c52107a..afd8afc5ea 100644 --- a/compiler/GHC/Core/Opt/SpecConstr.hs +++ b/compiler/GHC/Core/Opt/SpecConstr.hs @@ -1181,8 +1181,8 @@ data ArgOcc = NoOcc -- Doesn't occur at all; or a type argument | ScrutOcc -- See Note [ScrutOcc] (DataConEnv [ArgOcc]) -- How the sub-components are used -{- Note [ScrutOcc] -~~~~~~~~~~~~~~~~~~~ +{- Note [ScrutOcc] +~~~~~~~~~~~~~~~~~~ An occurrence of ScrutOcc indicates that the thing, or a `cast` version of the thing, is *only* taken apart or applied. @@ -1316,7 +1316,7 @@ scExpr' env (Let (NonRec bndr rhs) body) ; rhs_info <- scRecRhs env (bndr',rhs) ; let body_env2 = extendHowBound body_env [bndr'] RecFun - -- Note [Local let bindings] + -- See Note [Local let bindings] rhs' = ri_new_rhs rhs_info body_env3 = extendValEnv body_env2 bndr' (isValue (sc_vals env) rhs') diff --git a/compiler/GHC/Core/Opt/Specialise.hs b/compiler/GHC/Core/Opt/Specialise.hs index 3c2d10823d..25e4859300 100644 --- a/compiler/GHC/Core/Opt/Specialise.hs +++ b/compiler/GHC/Core/Opt/Specialise.hs @@ -809,7 +809,7 @@ canSpecImport dflags fn tryWarnMissingSpecs :: DynFlags -> [Id] -> Id -> [CallInfo] -> CoreM () -- See Note [Warning about missed specialisations] tryWarnMissingSpecs dflags callers fn calls_for_fn - | isClassOpId fn = return () -- See Note [Missed specialization for ClassOps] + | isClassOpId fn = return () -- See Note [Missed specialisation for ClassOps] | wopt Opt_WarnMissedSpecs dflags && not (null callers) && allCallersInlined = doWarn $ WarningWithFlag Opt_WarnMissedSpecs @@ -1434,7 +1434,7 @@ specCalls spec_imp env existing_rules calls_for_me fn rhs -- See Note [Auto-specialisation and RULES] -- && not (certainlyWillInline (idUnfolding fn)) -- And it's not small --- See Note [Inline specialisation] for why we do not +-- See Note [Inline specialisations] for why we do not -- switch off specialisation for inline functions = -- pprTrace "specDefn: some" (ppr fn $$ ppr calls_for_me $$ ppr existing_rules) $ diff --git a/compiler/GHC/Core/Opt/WorkWrap.hs b/compiler/GHC/Core/Opt/WorkWrap.hs index 5b31f76ed1..6180a69ab8 100644 --- a/compiler/GHC/Core/Opt/WorkWrap.hs +++ b/compiler/GHC/Core/Opt/WorkWrap.hs @@ -821,7 +821,7 @@ mkWWBindPair ww_opts fn_id fn_info fn_args fn_body work_uniq div work_arity = length work_demands - -- See Note [Demand on the Worker] + -- See Note [Demand on the worker] single_call = saturatedByOneShots arity (demandInfo fn_info) worker_demand | single_call = mkWorkerDemand work_arity | otherwise = topDmd @@ -845,7 +845,7 @@ mkStrWrapperInlinePrag :: InlinePragma -> [CoreRule] -> InlinePragma -- See Note [Wrapper activation] mkStrWrapperInlinePrag (InlinePragma { inl_act = act, inl_rule = rule_info }) rules = InlinePragma { inl_src = SourceText "{-# INLINE" - , inl_inline = NoUserInlinePrag -- See Note [Wrapper NoUserInline] + , inl_inline = NoUserInlinePrag -- See Note [Wrapper NoUserInlinePrag] , inl_sat = Nothing , inl_act = activeAfter wrapper_phase , inl_rule = rule_info } -- RuleMatchInfo is (and must be) unaffected diff --git a/compiler/GHC/Core/Opt/WorkWrap/Utils.hs b/compiler/GHC/Core/Opt/WorkWrap/Utils.hs index 698a85988a..86e57286c1 100644 --- a/compiler/GHC/Core/Opt/WorkWrap/Utils.hs +++ b/compiler/GHC/Core/Opt/WorkWrap/Utils.hs @@ -576,7 +576,7 @@ wantToUnboxArg fam_envs ty (n :* sd) | Just (tc, tc_args, co) <- normSplitTyConApp_maybe fam_envs ty , Just dc <- tyConSingleAlgDataCon_maybe tc , let arity = dataConRepArity dc - , Just (Unboxed, ds) <- viewProd arity sd -- See Note [Boxity Analysis] + , Just (Unboxed, ds) <- viewProd arity sd -- See Note [Boxity analysis] -- NB: No strictness or evaluatedness checks here. That is done by -- 'finaliseBoxity'! = Unbox (DataConPatContext dc tc_args co) ds diff --git a/compiler/GHC/Core/TyCo/Subst.hs b/compiler/GHC/Core/TyCo/Subst.hs index ec77cd2671..32817ca6c7 100644 --- a/compiler/GHC/Core/TyCo/Subst.hs +++ b/compiler/GHC/Core/TyCo/Subst.hs @@ -179,8 +179,8 @@ variations happen to; for example [a -> (a, b)]. A TCvSubst is not idempotent, but, unlike the non-idempotent substitution we use during unifications, it must not be repeatedly applied. -Note [Extending the TvSubstEnv] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Note [Extending the TCvSubstEnv] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See #tcvsubst_invariant# for the invariants that must hold. This invariant allows a short-cut when the subst envs are empty: diff --git a/compiler/GHC/Core/TyCon.hs b/compiler/GHC/Core/TyCon.hs index 7c4ad2dfcf..df8bf09fa0 100644 --- a/compiler/GHC/Core/TyCon.hs +++ b/compiler/GHC/Core/TyCon.hs @@ -442,7 +442,7 @@ See #19367. type TyConBinder = VarBndr TyVar TyConBndrVis type TyConTyCoBinder = VarBndr TyCoVar TyConBndrVis -- Only PromotedDataCon has TyConTyCoBinders - -- See Note [Promoted GADT data construtors] + -- See Note [Promoted GADT data constructors] data TyConBndrVis = NamedTCB ArgFlag @@ -1712,7 +1712,7 @@ isGcPtrRep UnliftedRep = True isGcPtrRep _ = False -- A PrimRep is compatible with another iff one can be coerced to the other. --- See Note [bad unsafe coercion] in GHC.Core.Lint for when are two types coercible. +-- See Note [Bad unsafe coercion] in GHC.Core.Lint for when are two types coercible. primRepCompatible :: Platform -> PrimRep -> PrimRep -> Bool primRepCompatible platform rep1 rep2 = (isUnboxed rep1 == isUnboxed rep2) && @@ -2436,7 +2436,7 @@ setTcTyConKind :: TyCon -> Kind -> TyCon -- Update the Kind of a TcTyCon -- The new kind is always a zonked version of its previous -- kind, so we don't need to update any other fields. --- See Note [The Purely Kinded Invariant] in GHC.Tc.Gen.HsType +-- See Note [The Purely Kinded Type Invariant (PKTI)] in GHC.Tc.Gen.HsType setTcTyConKind tc@(TcTyCon {}) kind = let tc' = tc { tyConKind = kind , tyConNullaryTy = mkNakedTyConTy tc' -- see Note [Sharing nullary TyCons] diff --git a/compiler/GHC/Core/Unfold.hs b/compiler/GHC/Core/Unfold.hs index 08c5a10b30..c341107957 100644 --- a/compiler/GHC/Core/Unfold.hs +++ b/compiler/GHC/Core/Unfold.hs @@ -1246,8 +1246,12 @@ tryUnfolding logger opts !case_depth id lone_variable {- -Note [Unfold into lazy contexts], Note [RHS of lets] +Note [Unfold into lazy contexts] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Merged into Note [RHS of lets]. + +Note [RHS of lets] +~~~~~~~~~~~~~~~~~~ When the call is the argument of a function with a RULE, or the RHS of a let, we are a little bit keener to inline. For example f y = (y,y,y) diff --git a/compiler/GHC/Core/Utils.hs b/compiler/GHC/Core/Utils.hs index 244f5f4b42..24ab87ac06 100644 --- a/compiler/GHC/Core/Utils.hs +++ b/compiler/GHC/Core/Utils.hs @@ -1218,12 +1218,12 @@ there is only dictionary selection (no construction) involved Note [exprIsCheap] ~~~~~~~~~~~~~~~~~~ -See also Note [Interaction of exprIsCheap and lone variables] in GHC.Core.Unfold +See also Note [Interaction of exprIsWorkFree and lone variables] in GHC.Core.Unfold @exprIsCheap@ looks at a Core expression and returns \tr{True} if it is obviously in weak head normal form, or is cheap to get to WHNF. -[Note that that's not the same as exprIsDupable; an expression might be -big, and hence not dupable, but still cheap.] +Note that that's not the same as exprIsDupable; an expression might be +big, and hence not dupable, but still cheap. By ``cheap'' we mean a computation we're willing to: push inside a lambda, or @@ -1951,7 +1951,7 @@ exprIsHNFlike is_con is_con_unf = is_hnf_like {- Note [exprIsHNF Tick] - +~~~~~~~~~~~~~~~~~~~~~ We can discard source annotations on HNFs as long as they aren't tick-like: @@ -2338,7 +2338,9 @@ There are some particularly delicate points here: The above is correct, but eta-reducing g would yield g=f, the linter will complain that g and f don't have the same type. -* Note [Arity care]: we need to be careful if we just look at f's +* Note [Arity care] + ~~~~~~~~~~~~~~~~~ + We need to be careful if we just look at f's arity. Currently (Dec07), f's arity is visible in its own RHS (see Note [Arity robustness] in GHC.Core.Opt.Simplify.Env) so we must *not* trust the arity when checking that 'f' is a value. Otherwise we will diff --git a/compiler/GHC/CoreToStg/Prep.hs b/compiler/GHC/CoreToStg/Prep.hs index afff96e6ed..99c4cd4e8c 100644 --- a/compiler/GHC/CoreToStg/Prep.hs +++ b/compiler/GHC/CoreToStg/Prep.hs @@ -82,9 +82,8 @@ import Data.Functor.Identity import Control.Monad {- --- --------------------------------------------------------------------------- --- Note [CorePrep Overview] --- --------------------------------------------------------------------------- +Note [CorePrep Overview] +~~~~~~~~~~~~~~~~~~~~~~~~ The goal of this pass is to prepare for code generation. @@ -2173,7 +2172,7 @@ newVar ty -- --------------------------------------------------------------------------- -- -- Note [Floating Ticks in CorePrep] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- It might seem counter-intuitive to float ticks by default, given -- that we don't actually want to move them if we can help it. On the -- other hand, nothing gets very far in CorePrep anyway, and we want diff --git a/compiler/GHC/Data/FastString.hs b/compiler/GHC/Data/FastString.hs index 1b2f21c415..1d9e419418 100644 --- a/compiler/GHC/Data/FastString.hs +++ b/compiler/GHC/Data/FastString.hs @@ -430,7 +430,7 @@ mkFastString# a# = mkFastStringBytes ptr (ptrStrLength ptr) where ptr = Ptr a# {- Note [Updating the FastString table] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We use a concurrent hashtable which contains multiple segments, each hash value always maps to the same segment. Read is lock-free, write to the a segment should acquire a lock for that segment to avoid race condition, writes to diff --git a/compiler/GHC/Driver/CmdLine.hs b/compiler/GHC/Driver/CmdLine.hs index b1226ecdca..539f27c53e 100644 --- a/compiler/GHC/Driver/CmdLine.hs +++ b/compiler/GHC/Driver/CmdLine.hs @@ -320,15 +320,15 @@ missingArgErr f = Left ("missing argument for flag: " ++ f) -------------------------------------------------------- --- See Note [Handling errors when parsing flags] +-- See Note [Handling errors when parsing command-line flags] errorsToGhcException :: [(String, -- Location String)] -- Error -> GhcException errorsToGhcException errs = UsageError $ intercalate "\n" $ [ l ++ ": " ++ e | (l, e) <- errs ] -{- Note [Handling errors when parsing commandline flags] - +{- Note [Handling errors when parsing command-line flags] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parsing of static and mode flags happens before any session is started, i.e., before the first call to 'GHC.withGhc'. Therefore, to report errors for invalid usage of these two types of flags, we can not call any function that diff --git a/compiler/GHC/Driver/Flags.hs b/compiler/GHC/Driver/Flags.hs index df833b03d1..b8a82656e8 100644 --- a/compiler/GHC/Driver/Flags.hs +++ b/compiler/GHC/Driver/Flags.hs @@ -320,7 +320,7 @@ data GeneralFlag | Opt_ShowHoleConstraints -- Options relating to the display of valid hole fits -- when generating an error message for a typed hole - -- See Note [Valid hole fits include] in GHC.Tc.Errors.Hole + -- See Note [Valid hole fits include ...] in GHC.Tc.Errors.Hole | Opt_ShowValidHoleFits | Opt_SortValidHoleFits | Opt_SortBySizeHoleFits diff --git a/compiler/GHC/Driver/Main.hs b/compiler/GHC/Driver/Main.hs index 5c088cc959..3e48771ace 100644 --- a/compiler/GHC/Driver/Main.hs +++ b/compiler/GHC/Driver/Main.hs @@ -839,8 +839,7 @@ initModDetails hsc_env mod_summary iface = {- Note [ModDetails and --make mode] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An interface file consists of two parts * The `ModIface` which ends up getting written to disk. @@ -957,7 +956,6 @@ hscDesugarAndSimplify summary (FrontendTypecheck tc_result) tc_warnings mb_old_h {- Note [Writing interface files] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We write one interface file per module and per compilation, except with -dynamic-too where we write two interface files (non-dynamic and dynamic). @@ -1762,7 +1760,6 @@ hscCompileCmmFile hsc_env filename output_filename = runHsc hsc_env $ do {- Note [Forcing of stg_binds] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The two last steps in the STG pipeline are: * Sorting the bindings in dependency order. @@ -2073,7 +2070,6 @@ hscAddSptEntries hsc_env mnwib entries = do {- Note [Fixity declarations in GHCi] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To support fixity declarations on types defined within GHCi (as requested in #10018) we record the fixity environment in InteractiveContext. When we want to evaluate something GHC.Tc.Module.runTcInteractive pulls out this diff --git a/compiler/GHC/Driver/Make.hs b/compiler/GHC/Driver/Make.hs index fb823e842f..4ec6d13348 100644 --- a/compiler/GHC/Driver/Make.hs +++ b/compiler/GHC/Driver/Make.hs @@ -447,7 +447,7 @@ loadWithCache cache how_much = do else throwErrors (fmap GhcDriverMessage errs) -- Note [Unused packages] --- +-- ~~~~~~~~~~~~~~~~~~~~~~ -- Cabal passes `--package-id` flag for each direct dependency. But GHC -- loads them lazily, so when compilation is done, we have a list of all -- actually loaded packages. All the packages, specified on command line, @@ -846,7 +846,6 @@ a pair of an `IO a` action and a `MVar a`, where to place the result. Note [--make mode] ~~~~~~~~~~~~~~~~~ - There are two main parts to `--make` mode. 1. `downsweep`: Starts from the top of the module graph and computes dependencies. @@ -857,7 +856,6 @@ computers how to build this ModuleGraph. Note [Upsweep] ~~~~~~~~~~~~~~ - Upsweep takes a 'ModuleGraph' as input, computes a build plan and then executes the plan in order to compile the project. @@ -2638,7 +2636,7 @@ waitMakeAction :: MakeAction -> IO () waitMakeAction (MakeAction _ mvar) = () <$ readMVar mvar {- Note [GHC Heap Invariants] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~ This note is a general place to explain some of the heap invariants which should hold for a program compiled with --make mode. These invariants are all things which can be checked easily using ghc-debug. diff --git a/compiler/GHC/Driver/Pipeline.hs b/compiler/GHC/Driver/Pipeline.hs index 3aaf9f298e..56e188395e 100644 --- a/compiler/GHC/Driver/Pipeline.hs +++ b/compiler/GHC/Driver/Pipeline.hs @@ -303,7 +303,7 @@ compileOne' mHscMessage = (Interpreter, gopt_set (dflags2 { backend = Interpreter }) Opt_ForceRecomp) | otherwise = (backend dflags, dflags2) - -- Note [Filepaths and Multiple Home Units] + -- See Note [Filepaths and Multiple Home Units] dflags = dflags3 { includePaths = offsetIncludePaths dflags3 $ addImplicitQuoteInclude old_paths [current_dir] } upd_summary = summary { ms_hspp_opts = dflags } hsc_env = hscSetFlags dflags hsc_env0 @@ -314,7 +314,6 @@ compileOne' mHscMessage -- -- Note [Dynamic linking on macOS] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Since macOS Sierra (10.14), the dynamic system linker enforces -- a limit on the Load Commands. Specifically the Load Command Size -- Limit is at 32K (32768). The Load Commands contain the install @@ -906,10 +905,8 @@ pipelineStart pipe_env hsc_env input_fn = fromSuffix _ = return (Just input_fn) {- - Note [The Pipeline Monad] ~~~~~~~~~~~~~~~~~~~~~~~~~ - The pipeline is represented as a free monad by the `TPipelineClass` type synonym, which stipulates the general monadic interface for the pipeline and `MonadUse`, instantiated to `TPhase`, which indicates the actions available in the pipeline. diff --git a/compiler/GHC/Driver/Pipeline/Execute.hs b/compiler/GHC/Driver/Pipeline/Execute.hs index 970c00eab2..6bc9df7c6f 100644 --- a/compiler/GHC/Driver/Pipeline/Execute.hs +++ b/compiler/GHC/Driver/Pipeline/Execute.hs @@ -171,7 +171,7 @@ runMergeForeign _pipe_env hsc_env input_fn foreign_os = do runLlvmLlcPhase :: PipeEnv -> HscEnv -> FilePath -> IO FilePath runLlvmLlcPhase pipe_env hsc_env input_fn = do -- Note [Clamping of llc optimizations] - -- + -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- See #13724 -- -- we clamp the llc optimization between [1,2]. This is because passing -O0 @@ -1077,7 +1077,6 @@ compileStub hsc_env stub_c = compileForeign hsc_env LangC stub_c {- Note [Produce big objects on Windows] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Windows Portable Executable object format has a limit of 32k sections, which we tend to blow through pretty easily. Thankfully, there is a "big object" extension, which raises this limit to 2^32. However, it must be explicitly @@ -1272,7 +1271,7 @@ getGhcVersionPathName dflags unit_env = do -- + 3c: R_SPARC_HI22 _GLOBAL_OFFSET_TABLE_-0x8 {- Note [Don't normalise input filenames] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Summary We used to normalise input filenames when starting the unlit phase. This broke hpc in `--make` mode with imported literate modules (#2991). diff --git a/compiler/GHC/Driver/Session.hs b/compiler/GHC/Driver/Session.hs index 0c4503a085..838f0bf3b7 100644 --- a/compiler/GHC/Driver/Session.hs +++ b/compiler/GHC/Driver/Session.hs @@ -1883,7 +1883,7 @@ parseDynamicFlagsFull activeFlags cmdline dflags0 args = do let ((leftover, errs, warns), dflags1) = runCmdLine (processArgs activeFlags args) dflags0 - -- See Note [Handling errors when parsing commandline flags] + -- See Note [Handling errors when parsing command-line flags] let rdr = renderWithContext (initSDocContext dflags0 defaultUserStyle) unless (null errs) $ liftIO $ throwGhcExceptionIO $ errorsToGhcException $ map ((rdr . ppr . getLoc &&& unLoc) . errMsg) $ errs @@ -4586,8 +4586,8 @@ pieCCLDOpts dflags {- -Note [No PIE while linking] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Note [No PIE when linking] +~~~~~~~~~~~~~~~~~~~~~~~~~~ As of 2016 some Linux distributions (e.g. Debian) have started enabling -pie by default in their gcc builds. This is incompatible with -r as it implies that we are producing an executable. Consequently, we must manually pass -no-pie to gcc diff --git a/compiler/GHC/HsToCore/Coverage.hs b/compiler/GHC/HsToCore/Coverage.hs index 2e45539fba..20086620e5 100644 --- a/compiler/GHC/HsToCore/Coverage.hs +++ b/compiler/GHC/HsToCore/Coverage.hs @@ -400,7 +400,7 @@ bindTick density name pos fvs = do -- Note [inline sccs] --- +-- ~~~~~~~~~~~~~~~~~~ -- The reason not to add ticks to INLINE functions is that this is -- sometimes handy for avoiding adding a tick to a particular function -- (see #6131) @@ -1080,6 +1080,7 @@ noFVs :: FreeVars noFVs = emptyOccEnv -- Note [freevars] +-- ~~~~~~~~~~~~~~~ -- For breakpoints we want to collect the free variables of an -- expression for pinning on the HsTick. We don't want to collect -- *all* free variables though: in particular there's no point pinning diff --git a/compiler/GHC/HsToCore/Match.hs b/compiler/GHC/HsToCore/Match.hs index 28391fa815..7719e14192 100644 --- a/compiler/GHC/HsToCore/Match.hs +++ b/compiler/GHC/HsToCore/Match.hs @@ -254,7 +254,7 @@ match (v:vs) ty eqns -- Eqns *can* be empty maybeWarn $ filter (not . null) gs matchEmpty :: MatchId -> Type -> DsM (NonEmpty (MatchResult CoreExpr)) --- See Note [Empty case expressions] +-- See Note [Empty case alternatives] matchEmpty var res_ty = return [MR_Fallible mk_seq] where @@ -343,7 +343,7 @@ We do *not* desugar simply to error "empty case" or some such, because 'x' might be bound to (error "hello"), in which case we want to see that "hello" exception, not (error "empty case"). -See also Note [Case elimination: lifted case] in GHC.Core.Opt.Simplify. +See also the "lifted case" discussion in Note [Case elimination] in GHC.Core.Opt.Simplify. ************************************************************************ diff --git a/compiler/GHC/HsToCore/Pmc/Solver.hs b/compiler/GHC/HsToCore/Pmc/Solver.hs index 7623c6e710..b19ce0c475 100644 --- a/compiler/GHC/HsToCore/Pmc/Solver.hs +++ b/compiler/GHC/HsToCore/Pmc/Solver.hs @@ -1004,7 +1004,7 @@ The term oracle state is never obviously (i.e., without consulting the type oracle or doing inhabitation testing) contradictory. This implies a few invariants: * Whenever vi_pos overlaps with vi_neg according to 'eqPmAltCon', we refute. - This is implied by the Note [Pos/Neg invariant]. + This is implied by the Note [The Pos/Neg invariant]. * Whenever vi_neg subsumes a COMPLETE set, we refute. We consult vi_rcm to detect this, but we could just compare whole COMPLETE sets to vi_neg every time, if it weren't for performance. @@ -1496,7 +1496,7 @@ matchConLikeResTy _ (TySt _ inert) ty (PatSynCon ps) = {-# SCC "matchConLikeRe then pure subst else mzero -{- Note [Soundness and completeness] +{- Note [Soundness and Completeness] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Soundness and completeness of the pattern-match checker depend entirely on the soundness and completeness of the inhabitation test. diff --git a/compiler/GHC/HsToCore/Types.hs b/compiler/GHC/HsToCore/Types.hs index bc9d7b4c1d..e147758260 100644 --- a/compiler/GHC/HsToCore/Types.hs +++ b/compiler/GHC/HsToCore/Types.hs @@ -70,7 +70,7 @@ data DsLclEnv { dsl_meta :: DsMetaEnv -- ^ Template Haskell bindings , dsl_loc :: RealSrcSpan -- ^ To put in pattern-matching error msgs , dsl_nablas :: Nablas - -- ^ See Note [Note [Long-distance information] in "GHC.HsToCore.Pmc". + -- ^ See Note [Long-distance information] in "GHC.HsToCore.Pmc". -- The set of reaching values Nablas is augmented as we walk inwards, refined -- through each pattern match in turn } diff --git a/compiler/GHC/Iface/Ext/Ast.hs b/compiler/GHC/Iface/Ext/Ast.hs index 83eb475a78..cc694f249f 100644 --- a/compiler/GHC/Iface/Ext/Ast.hs +++ b/compiler/GHC/Iface/Ext/Ast.hs @@ -78,7 +78,7 @@ import Control.Monad.Trans.Class ( lift ) import Control.Applicative ( (<|>) ) {- Note [Updating HieAst for changes in the GHC AST] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When updating the code in this file for changes in the GHC AST, you need to pay attention to the following things: @@ -210,6 +210,7 @@ type TypecheckedSource = LHsBinds GhcTc {- Note [Name Remapping] + ~~~~~~~~~~~~~~~~~~~~~ The Typechecker introduces new names for mono names in AbsBinds. We don't care about the distinction between mono and poly bindings, so we replace all occurrences of the mono name with the poly name. @@ -415,6 +416,7 @@ concatM :: Monad m => [m [a]] -> m [a] concatM xs = concat <$> sequence xs {- Note [Capturing Scopes and other non local information] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ toHie is a local transformation, but scopes of bindings cannot be known locally, hence we have to push the relevant info down into the binding nodes. We use the following types (*Context and *Scoped) to wrap things and @@ -459,6 +461,7 @@ data PScoped a = PS (Maybe Span) deriving (Typeable, Data) -- Pattern Scope {- Note [TyVar Scopes] + ~~~~~~~~~~~~~~~~~~~ Due to -XScopedTypeVariables, type variables can be in scope quite far from their original binding. We resolve the scope of these type variables in a separate pass @@ -512,6 +515,7 @@ tvScopes tvScope rhsScope xs = map (\(RS sc a)-> TVS tvScope sc a) $ listScopes rhsScope xs {- Note [Scoping Rules for SigPat] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Explicitly quantified variables in pattern type signatures are not brought into scope in the rhs, but implicitly quantified variables are (HsWC and HsIB). diff --git a/compiler/GHC/Iface/Recomp.hs b/compiler/GHC/Iface/Recomp.hs index fc12701b61..2c1943074c 100644 --- a/compiler/GHC/Iface/Recomp.hs +++ b/compiler/GHC/Iface/Recomp.hs @@ -1474,6 +1474,7 @@ declExtras fix_fn ann_fn rule_env inst_env fi_env dm_env decl {- Note [default method Name] (see also #15970) + ~~~~~~~~~~~~~~~~~~~~~~~~~~ The Names for the default methods aren't available in Iface syntax. diff --git a/compiler/GHC/Iface/Recomp/Flags.hs b/compiler/GHC/Iface/Recomp/Flags.hs index ace07c5977..90f3afebbc 100644 --- a/compiler/GHC/Iface/Recomp/Flags.hs +++ b/compiler/GHC/Iface/Recomp/Flags.hs @@ -109,7 +109,7 @@ fingerprintHpcFlags dflags@DynFlags{..} nameio = {- Note [path flags and recompilation] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are several flags that we deliberately omit from the recompilation check; here we explain why. @@ -140,7 +140,6 @@ The only path-related flag left is -hcsuf. {- Note [Ignoring some flag changes] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Normally, --make tries to reuse only compilation products that are the same as those that would have been produced compiling from scratch. Sometimes, however, users would like to be more aggressive @@ -159,7 +158,6 @@ options out of the flag hash, hashing them separately. {- Note [Repeated -optP hashing] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We invoke fingerprintDynFlags for each compiled module to include the hash of relevant DynFlags in the resulting interface file. -optP (preprocessor) flags are part of that hash. diff --git a/compiler/GHC/Linker/Loader.hs b/compiler/GHC/Linker/Loader.hs index a3a2059f07..046ec5ffd7 100644 --- a/compiler/GHC/Linker/Loader.hs +++ b/compiler/GHC/Linker/Loader.hs @@ -444,7 +444,7 @@ mergeStaticObjects specs = go [] specs go [] [] = [] {- Note [preload packages] - + ~~~~~~~~~~~~~~~~~~~~~~~ Why do we need to preload packages from the command line? This is an explanation copied from #2437: diff --git a/compiler/GHC/Rename/Env.hs b/compiler/GHC/Rename/Env.hs index a3c126222f..e19697bb40 100644 --- a/compiler/GHC/Rename/Env.hs +++ b/compiler/GHC/Rename/Env.hs @@ -1430,7 +1430,7 @@ lookupGreRn_maybe fos rdr_name {- Note [ Unbound vs Ambiguous Names ] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ lookupGreRn_maybe deals with failures in two different ways. If a name is unbound then we return a `Nothing` but if the name is ambiguous then we raise an error and return a dummy name. diff --git a/compiler/GHC/Rename/Expr.hs b/compiler/GHC/Rename/Expr.hs index 837d2b55e8..bb529c8066 100644 --- a/compiler/GHC/Rename/Expr.hs +++ b/compiler/GHC/Rename/Expr.hs @@ -1720,7 +1720,7 @@ ApplicativeDo ************************************************************************ Note [ApplicativeDo] - +~~~~~~~~~~~~~~~~~~~~ = Example = For a sequence of statements diff --git a/compiler/GHC/Rename/Unbound.hs b/compiler/GHC/Rename/Unbound.hs index 5bbc2927ab..6d48ea3074 100644 --- a/compiler/GHC/Rename/Unbound.hs +++ b/compiler/GHC/Rename/Unbound.hs @@ -232,6 +232,7 @@ similarNameSuggestions looking_for@(LF what_look where_look) dflags global_env ([], []) -> [] ] -- Note [Only-quals] + -- ~~~~~~~~~~~~~~~~~ -- The second alternative returns those names with the same -- OccName as the one we tried, but live in *qualified* imports -- e.g. if you have: diff --git a/compiler/GHC/Runtime/Eval.hs b/compiler/GHC/Runtime/Eval.hs index b99ffe905a..f95ef3a5d0 100644 --- a/compiler/GHC/Runtime/Eval.hs +++ b/compiler/GHC/Runtime/Eval.hs @@ -691,7 +691,7 @@ pushResume hsc_env resume = hsc_env { hsc_IC = ictxt1 } {- Note [Syncing breakpoint info] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To display the values of the free variables for a single breakpoint, the function `GHC.Runtime.Eval.bindLocalsAtBreakpoint` pulls out the information from the fields `modBreaks_breakInfo` and diff --git a/compiler/GHC/Runtime/Interpreter.hs b/compiler/GHC/Runtime/Interpreter.hs index 10d2520f18..2c84980513 100644 --- a/compiler/GHC/Runtime/Interpreter.hs +++ b/compiler/GHC/Runtime/Interpreter.hs @@ -121,7 +121,7 @@ import System.Process import GHC.Conc (pseq, par) {- Note [Remote GHCi] - + ~~~~~~~~~~~~~~~~~~ When the flag -fexternal-interpreter is given to GHC, interpreted code is run in a separate process called iserv, and we communicate with the external process over a pipe using Binary-encoded messages. @@ -200,7 +200,7 @@ interpCmd interp msg = case interpInstance interp of -- Note [uninterruptibleMask_ and interpCmd] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- If we receive an async exception, such as ^C, while communicating -- with the iserv process then we will be out-of-sync and not be able -- to recover. Thus we use uninterruptibleMask_ during @@ -510,6 +510,7 @@ unloadObj interp path = do interpCmd interp (UnloadObj path') -- Note [loadObj and relative paths] +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- the iserv process might have a different current directory from the -- GHC process, so we must make paths absolute before sending them -- over. @@ -635,7 +636,7 @@ runWithPipes createProc prog opts = do -- ----------------------------------------------------------------------------- {- Note [External GHCi pointers] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We have the following ways to reference things in GHCi: HValue diff --git a/compiler/GHC/StgToByteCode.hs b/compiler/GHC/StgToByteCode.hs index a69fe69872..ab5d0fb5bc 100644 --- a/compiler/GHC/StgToByteCode.hs +++ b/compiler/GHC/StgToByteCode.hs @@ -157,7 +157,7 @@ allocateTopStrings interp topStrings = do {- Note [generating code for top-level string literal bindings] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here is a summary on how the byte code generator deals with top-level string literals: @@ -1102,7 +1102,6 @@ layoutTuple profile start_off arg_ty reps = {- Note [unboxed tuple bytecodes and tuple_BCO] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We have the bytecode instructions RETURN_TUPLE and PUSH_ALTS_TUPLE to return and receive arbitrary unboxed tuples, respectively. These instructions use the helper data tuple_BCO and tuple_info. @@ -1782,7 +1781,9 @@ mkMultiBranch maybe_ncons raw_ways = do | otherwise = return (testEQ (fst val) lbl_default `consOL` snd val) - -- Note [CASEFAIL] It may be that this case has no default + -- Note [CASEFAIL] + -- ~~~~~~~~~~~~~~~ + -- It may be that this case has no default -- branch, but the alternatives are not exhaustive - this -- happens for GADT cases for example, where the types -- prove that certain branches are impossible. We could diff --git a/compiler/GHC/StgToCmm/Bind.hs b/compiler/GHC/StgToCmm/Bind.hs index 3f935c848d..435f55106b 100644 --- a/compiler/GHC/StgToCmm/Bind.hs +++ b/compiler/GHC/StgToCmm/Bind.hs @@ -149,7 +149,7 @@ cgBind (StgRec pairs) ; emit (catAGraphs inits <*> body) } {- Note [cgBind rec] - + ~~~~~~~~~~~~~~~~~ Recursive let-bindings are tricky. Consider the following pseudocode: @@ -268,7 +268,7 @@ for semi-obvious reasons. -} ----------- Note [Selectors] ------------------ +---------- See Note [Selectors] ------------------ mkRhsClosure profile bndr _cc [NonVoid the_fv] -- Just one free var upd_flag -- Updatable thunk @@ -301,7 +301,7 @@ mkRhsClosure profile bndr _cc let lf_info = mkSelectorLFInfo bndr offset_into_int (isUpdatable upd_flag) in cgRhsStdThunk bndr lf_info [StgVarArg the_fv] ----------- Note [Ap thunks] ------------------ +---------- See Note [Ap thunks] ------------------ mkRhsClosure profile bndr _cc fvs upd_flag @@ -526,7 +526,6 @@ closureCodeBody top_lvl bndr cl_info cc args@(arg0:_) body fv_details -- Note [NodeReg clobbered with loopification] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Previously we used to pass nodeReg (aka R1) here. With profiling, upon -- entering a closure, enterFunCCS was called with R1 passed to it. But since R1 -- may get clobbered inside the body of a closure, and since a self-recursive diff --git a/compiler/GHC/StgToCmm/Foreign.hs b/compiler/GHC/StgToCmm/Foreign.hs index 4c414df9e9..a1ee175bad 100644 --- a/compiler/GHC/StgToCmm/Foreign.hs +++ b/compiler/GHC/StgToCmm/Foreign.hs @@ -127,7 +127,7 @@ cgForeignCall (CCall (CCallSpec target cconv safety)) typ stg_args res_ty } {- Note [safe foreign call convention] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The simple thing to do for a safe foreign call would be the same as an unsafe one: just diff --git a/compiler/GHC/StgToCmm/Heap.hs b/compiler/GHC/StgToCmm/Heap.hs index 39a7812b70..ec61ef2406 100644 --- a/compiler/GHC/StgToCmm/Heap.hs +++ b/compiler/GHC/StgToCmm/Heap.hs @@ -491,6 +491,7 @@ cannedGCEntryPoint platform regs _otherwise -> Nothing -- Note [stg_gc arguments] +-- ~~~~~~~~~~~~~~~~~~~~~~~ -- It might seem that we could avoid passing the arguments to the -- stg_gc function, because they are already in the right registers. -- While this is usually the case, it isn't always. Sometimes the @@ -670,7 +671,6 @@ do_checks mb_stk_hwm checkYield mb_alloc_lit do_gc = do -- Note [Self-recursive loop header] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --- -- Self-recursive loop header is required by loopification optimization (See -- Note [Self-recursive tail calls] in GHC.StgToCmm.Expr). We emit it if: -- diff --git a/compiler/GHC/StgToCmm/Layout.hs b/compiler/GHC/StgToCmm/Layout.hs index 9e14d1e766..5664be908e 100644 --- a/compiler/GHC/StgToCmm/Layout.hs +++ b/compiler/GHC/StgToCmm/Layout.hs @@ -212,7 +212,7 @@ slowCall fun stg_args " with pat " ++ unpackFS rts_fun) return r - -- Note [avoid intermediate PAPs] + -- See Note [avoid intermediate PAPs] let n_args = length stg_args if n_args > arity && fast_pap then do @@ -261,7 +261,7 @@ slowCall fun stg_args -- Note [avoid intermediate PAPs] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- A slow call which needs multiple generic apply patterns will be -- almost guaranteed to create one or more intermediate PAPs when -- applied to a function that takes the correct number of arguments. @@ -339,7 +339,7 @@ nonVArgs ((_,Just arg) : args) = arg : nonVArgs args {- Note [over-saturated calls] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~ The natural thing to do for an over-saturated call would be to call the function with the correct number of arguments, and then apply the remaining arguments to the value returned, e.g. diff --git a/compiler/GHC/StgToCmm/Monad.hs b/compiler/GHC/StgToCmm/Monad.hs index d8d6600268..5ab12a4634 100644 --- a/compiler/GHC/StgToCmm/Monad.hs +++ b/compiler/GHC/StgToCmm/Monad.hs @@ -203,7 +203,7 @@ data ReturnKind | ReturnedTo BlockId ByteOff -- Note [sharing continuations] --- +-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ReturnKind says how the expression being compiled returned its -- results: either by assigning directly to the registers specified -- by the Sequel, or by returning to a continuation that does the diff --git a/compiler/GHC/StgToCmm/Prim.hs b/compiler/GHC/StgToCmm/Prim.hs index 766a6e8a9c..b980c0aacd 100644 --- a/compiler/GHC/StgToCmm/Prim.hs +++ b/compiler/GHC/StgToCmm/Prim.hs @@ -74,7 +74,7 @@ cgOpApp :: StgOp -- The op -- Foreign calls cgOpApp (StgFCallOp fcall ty) stg_args res_ty = cgForeignCall fcall ty stg_args res_ty - -- Note [Foreign call results] + -- See Note [Foreign call results] cgOpApp (StgPrimOp primop) args res_ty = do cfg <- getStgToCmmConfig @@ -1716,7 +1716,6 @@ emitPrimOp cfg primop = alwaysExternal = \_ -> PrimopCmmEmit_External -- Note [QuotRem optimization] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- -- `quot` and `rem` with constant divisor can be implemented with fast bit-ops -- (shift, .&.). -- diff --git a/compiler/GHC/SysTools.hs b/compiler/GHC/SysTools.hs index 0b19d50825..adc6e6c241 100644 --- a/compiler/GHC/SysTools.hs +++ b/compiler/GHC/SysTools.hs @@ -156,8 +156,8 @@ initSysTools top_dir = do Left (SettingsError_MissingData msg) -> pgmError msg Left (SettingsError_BadData msg) -> pgmError msg -{- Note [Windows stack usage] - +{- Note [Windows stack allocations] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See: #8870 (and #8834 for related info) and #12186 On Windows, occasionally we need to grow the stack. In order to do diff --git a/compiler/GHC/SysTools/BaseDir.hs b/compiler/GHC/SysTools/BaseDir.hs index 54c42e7c52..312c029dd9 100644 --- a/compiler/GHC/SysTools/BaseDir.hs +++ b/compiler/GHC/SysTools/BaseDir.hs @@ -35,7 +35,6 @@ import System.Directory (doesDirectoryExist) {- Note [topdir: How GHC finds its files] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - GHC needs various support files (library packages, RTS etc), plus various auxiliary programs (cp, gcc, etc). It starts by finding topdir, the root of GHC's support files @@ -54,7 +53,7 @@ from topdir we can find package.conf, ghc-asm, etc. Note [tooldir: How GHC finds mingw on Windows] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GHC has some custom logic on Windows for finding the mingw toolchain and perl. Depending on whether GHC is built with the make build system or Hadrian, and on whether we're diff --git a/compiler/GHC/SysTools/Info.hs b/compiler/GHC/SysTools/Info.hs index 83a76b9efb..81650495ba 100644 --- a/compiler/GHC/SysTools/Info.hs +++ b/compiler/GHC/SysTools/Info.hs @@ -26,7 +26,7 @@ import GHC.Prelude import GHC.SysTools.Process {- Note [Run-time linker info] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ See also: #5240, #6063, #10110 Before 'runLink', we need to be sure to get the relevant information @@ -57,7 +57,7 @@ circular dependency. -} {- Note [ELF needed shared libs] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some distributions change the link editor's default handling of ELF DT_NEEDED tags to include only those shared objects that are needed to resolve undefined symbols. For Template Haskell we need @@ -71,7 +71,7 @@ The flag is only needed on ELF systems. On Windows (PE) and Mac OS X -} {- Note [Windows static libGCC] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The GCC versions being upgraded to in #10726 are configured with dynamic linking of libgcc supported. This results in libgcc being linked dynamically when a shared library is created. @@ -177,10 +177,10 @@ getLinkerInfo' logger dflags = do "-Wl,--hash-size=31" , "-Wl,--reduce-memory-overheads" -- Emit gcc stack checks - -- Note [Windows stack usage] + -- See Note [Windows stack allocations] , "-fstack-check" -- Force static linking of libGCC - -- Note [Windows static libGCC] + -- See Note [Windows static libGCC] , "-static-libgcc" ] _ -> do -- In practice, we use the compiler as the linker here. Pass diff --git a/compiler/GHC/Tc/Errors.hs b/compiler/GHC/Tc/Errors.hs index 2901078004..70f5d0ddd7 100644 --- a/compiler/GHC/Tc/Errors.hs +++ b/compiler/GHC/Tc/Errors.hs @@ -1910,7 +1910,7 @@ mkDictErr ctxt cts -- but we really only want to report the latter elim_superclasses cts = mkMinimalBySCs ctPred cts --- [Note: mk_dict_err] +-- Note [mk_dict_err] -- ~~~~~~~~~~~~~~~~~~~ -- Different dictionary error messages are reported depending on the number of -- matches and unifiers: diff --git a/compiler/GHC/Tc/Gen/Splice.hs b/compiler/GHC/Tc/Gen/Splice.hs index fe6ec75568..747b3a7d98 100644 --- a/compiler/GHC/Tc/Gen/Splice.hs +++ b/compiler/GHC/Tc/Gen/Splice.hs @@ -1553,7 +1553,7 @@ readQResult i = do QFail str -> fail str {- Note [TH recover with -fexternal-interpreter] - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Recover is slightly tricky to implement. The meaning of "recover a b" is diff --git a/compiler/GHC/Tc/Instance/FunDeps.hs b/compiler/GHC/Tc/Instance/FunDeps.hs index 9abfc31f0b..4b45f2fa38 100644 --- a/compiler/GHC/Tc/Instance/FunDeps.hs +++ b/compiler/GHC/Tc/Instance/FunDeps.hs @@ -374,7 +374,7 @@ checkInstCoverage :: Bool -- Be liberal -> Class -> [PredType] -> [Type] -> Validity -- "be_liberal" flag says whether to use "liberal" coverage of --- See Note [Coverage Condition] below +-- See Note [Coverage condition] below -- -- Return values -- Nothing => no problems diff --git a/compiler/GHC/Tc/Solver/Interact.hs b/compiler/GHC/Tc/Solver/Interact.hs index a088637e46..36e9afae98 100644 --- a/compiler/GHC/Tc/Solver/Interact.hs +++ b/compiler/GHC/Tc/Solver/Interact.hs @@ -1632,8 +1632,8 @@ Now the second wanted comes along, but it cannot rewrite the given, so we simply At the end we spontaneously solve that guy, *reunifying* [alpha := Int] We avoid this problem by orienting the resulting given so that the unification -variable is on the left. [Note that alternatively we could attempt to -enforce this at canonicalization] +variable is on the left (note that alternatively we could attempt to +enforce this at canonicalization). See also Note [No touchables as FunEq RHS] in GHC.Tc.Solver.Monad; avoiding double unifications is the main reason we disallow touchable @@ -2177,7 +2177,7 @@ chooseInstance work_item ; if isDerived ev then -- Use type-class instances for Deriveds, in the hope -- of generating some improvements - -- C.f. Example 3 of Note [The improvement story] + -- C.f. Example 3 of Note [The improvement story and derived shadows] -- It's easy because no evidence is involved do { dflags <- getDynFlags ; unless (subGoalDepthExceeded dflags (ctLocDepth deeper_loc)) $ diff --git a/compiler/GHC/Tc/Types.hs b/compiler/GHC/Tc/Types.hs index 2de119b416..a784eb5719 100644 --- a/compiler/GHC/Tc/Types.hs +++ b/compiler/GHC/Tc/Types.hs @@ -1046,7 +1046,7 @@ thLevel (Brack s _) = thLevel s + 1 thLevel (RunSplice _) = panic "thLevel: called when running a splice" -- See Note [RunSplice ThLevel]. -{- Node [RunSplice ThLevel] +{- Note [RunSplice ThLevel] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'RunSplice' stage is set when executing a splice, and only when running a splice. In particular it is not set when the splice is renamed or typechecked. diff --git a/compiler/GHC/Tc/Types/Constraint.hs b/compiler/GHC/Tc/Types/Constraint.hs index ffe14b3d62..f1d59bf04b 100644 --- a/compiler/GHC/Tc/Types/Constraint.hs +++ b/compiler/GHC/Tc/Types/Constraint.hs @@ -2093,7 +2093,8 @@ but we do not want to complain about Bool ~ Char! Note [Deriveds do rewrite Deriveds] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ However we DO allow Deriveds to rewrite Deriveds, because that's how -improvement works; see Note [The improvement story] in GHC.Tc.Solver.Interact. +improvement works; see Note [The improvement story and derived shadows] in +GHC.Tc.Solver.Interact. However, for now at least I'm only letting (Derived,NomEq) rewrite (Derived,NomEq) and not doing anything for ReprEq. If we have diff --git a/compiler/GHC/Tc/Utils/TcMType.hs b/compiler/GHC/Tc/Utils/TcMType.hs index c510d29f63..22f9b14d26 100644 --- a/compiler/GHC/Tc/Utils/TcMType.hs +++ b/compiler/GHC/Tc/Utils/TcMType.hs @@ -2257,7 +2257,7 @@ Consider this: * So we get a dict binding for Num (C d a), which is zonked to give a = () - [Note Sept 04: now that we are zonking quantified type variables + Note (Sept 04): now that we are zonking quantified type variables on construction, the 'a' will be frozen as a regular tyvar on quantification, so the floated dict will still have type (C d a). Which renders this whole note moot; happily!] diff --git a/compiler/GHC/ThToHs.hs b/compiler/GHC/ThToHs.hs index 1020b5af3f..6703719797 100644 --- a/compiler/GHC/ThToHs.hs +++ b/compiler/GHC/ThToHs.hs @@ -1110,6 +1110,7 @@ cvt_tup es boxity = do { let cvtl_maybe Nothing = return (missingTupArg noAnn) boxity } {- Note [Operator association] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ We must be quite careful about adding parens: * Infix (UInfix ...) op arg Needs parens round the first arg * Infix (Infix ...) op arg Needs parens round the first arg diff --git a/compiler/GHC/Types/Name.hs b/compiler/GHC/Types/Name.hs index b34f32de43..d919919e81 100644 --- a/compiler/GHC/Types/Name.hs +++ b/compiler/GHC/Types/Name.hs @@ -199,6 +199,7 @@ TL;DR: we make the `n_occ` field lazy. {- Note [About the NameSorts] +~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Initially, top-level Ids (including locally-defined ones) get External names, and all other local Ids get Internal names diff --git a/compiler/GHC/Types/Name/Occurrence.hs b/compiler/GHC/Types/Name/Occurrence.hs index cb98413279..7aabf83dd9 100644 --- a/compiler/GHC/Types/Name/Occurrence.hs +++ b/compiler/GHC/Types/Name/Occurrence.hs @@ -132,6 +132,7 @@ data NameSpace = VarName -- Variables, including "real" data constructors deriving( Eq, Ord ) -- Note [Data Constructors] +-- ~~~~~~~~~~~~~~~~~~~~~~~~ -- see also: Note [Data Constructor Naming] in GHC.Core.DataCon -- -- $real_vs_source_data_constructors diff --git a/compiler/GHC/Types/Tickish.hs b/compiler/GHC/Types/Tickish.hs index 30827bb1fb..480bb2befd 100644 --- a/compiler/GHC/Types/Tickish.hs +++ b/compiler/GHC/Types/Tickish.hs @@ -59,7 +59,7 @@ data TickishPass {- Note [Tickish passes] - + ~~~~~~~~~~~~~~~~~~~~~ Tickish annotations store different information depending on where they are used. Here's a summary of the differences between the passes. diff --git a/compiler/GHC/Types/Var.hs b/compiler/GHC/Types/Var.hs index 5ca0d00028..0a6dc6079a 100644 --- a/compiler/GHC/Types/Var.hs +++ b/compiler/GHC/Types/Var.hs @@ -620,7 +620,7 @@ Currently there are nine different uses of 'VarBndr': * TyCon.TyConTyCoBinder = VarBndr TyCoVar TyConBndrVis Binders of a PromotedDataCon - See Note [Promoted GADT data construtors] in GHC.Core.TyCon + See Note [Promoted GADT data constructors] in GHC.Core.TyCon * IfaceType.IfaceForAllBndr = VarBndr IfaceBndr ArgFlag * IfaceType.IfaceForAllSpecBndr = VarBndr IfaceBndr Specificity diff --git a/compiler/GHC/Types/Var/Env.hs b/compiler/GHC/Types/Var/Env.hs index 683face5c9..55ea2a0dda 100644 --- a/compiler/GHC/Types/Var/Env.hs +++ b/compiler/GHC/Types/Var/Env.hs @@ -324,6 +324,7 @@ rnBndr2_var (RV2 { envL = envL, envR = envR, in_scope = in_scope }) bL bR | otherwise = uniqAway' in_scope bL -- Note [Rebinding] + -- ~~~~~~~~~~~~~~~~ -- If the new var is the same as the old one, note that -- the extendVarEnv *deletes* any current renaming -- E.g. (\x. \x. ...) ~ (\y. \z. ...) diff --git a/compiler/GHC/Unit.hs b/compiler/GHC/Unit.hs index 155d5b3525..4affdc33c8 100644 --- a/compiler/GHC/Unit.hs +++ b/compiler/GHC/Unit.hs @@ -20,10 +20,8 @@ import GHC.Unit.Home import GHC.Unit.State {- - -Note [About Units] +Note [About units] ~~~~~~~~~~~~~~~~~~ - Haskell users are used to manipulating Cabal packages. These packages are identified by: - a package name :: String diff --git a/compiler/GHC/Unit/State.hs b/compiler/GHC/Unit/State.hs index 8644848310..3e74ae9936 100644 --- a/compiler/GHC/Unit/State.hs +++ b/compiler/GHC/Unit/State.hs @@ -318,8 +318,8 @@ data UnitConfig = UnitConfig , unitConfigWays :: !Ways -- ^ Ways to use , unitConfigAllowVirtual :: !Bool -- ^ Allow virtual units - -- ^ Do we allow the use of virtual units instantiated on-the-fly (see Note - -- [About units] in GHC.Unit). This should only be true when we are + -- ^ Do we allow the use of virtual units instantiated on-the-fly (see + -- Note [About units] in GHC.Unit). This should only be true when we are -- type-checking an indefinite unit (not producing any code). , unitConfigProgramName :: !String @@ -1148,7 +1148,7 @@ findWiredInUnits logger prec_map pkgs vis_map = do -- every non instantiated unit is an instance of -- itself (required by Backpack...) -- - -- See Note [About Units] in GHC.Unit + -- See Note [About units] in GHC.Unit } | otherwise = pkg @@ -2180,7 +2180,7 @@ renameHoleModule :: UnitState -> ShHoleSubst -> Module -> Module renameHoleModule state = renameHoleModule' (unitInfoMap state) (preloadClosure state) -- | Substitutes holes in a 'Unit', suitable for renaming when --- an include occurs; see Note [Representation of module/name variable]. +-- an include occurs; see Note [Representation of module/name variables]. -- -- @p[A=\<A>]@ maps to @p[A=\<B>]@ with @A=\<B>@. renameHoleUnit :: UnitState -> ShHoleSubst -> Unit -> Unit diff --git a/compiler/GHC/Utils/Ppr.hs b/compiler/GHC/Utils/Ppr.hs index 9b5b55658f..af2b6f977a 100644 --- a/compiler/GHC/Utils/Ppr.hs +++ b/compiler/GHC/Utils/Ppr.hs @@ -22,7 +22,7 @@ {- Note [Differences between libraries/pretty and compiler/GHC/Utils/Ppr.hs] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For historical reasons, there are two different copies of `Pretty` in the GHC source tree: * `libraries/pretty` is a submodule containing @@ -441,7 +441,7 @@ braces p = char '{' <> p <> char '}' {- Note [Print Hexadecimal Literals] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Relevant discussions: * Phabricator: https://phabricator.haskell.org/D4465 * GHC Trac: https://gitlab.haskell.org/ghc/ghc/issues/14872 diff --git a/compiler/Language/Haskell/Syntax/Decls.hs b/compiler/Language/Haskell/Syntax/Decls.hs index fbeebf9213..b668d7fbff 100644 --- a/compiler/Language/Haskell/Syntax/Decls.hs +++ b/compiler/Language/Haskell/Syntax/Decls.hs @@ -430,7 +430,7 @@ data TyClDecl pass DataDecl { tcdDExt :: XDataDecl pass -- ^ Post renamer, CUSK flag, FVs , tcdLName :: LIdP pass -- ^ Type constructor , tcdTyVars :: LHsQTyVars pass -- ^ Type variables - -- See Note [TyVar binders for associated declarations] + -- See Note [TyVar binders for associated decls] , tcdFixity :: LexicalFixity -- ^ Fixity used in the declaration , tcdDataDefn :: HsDataDefn pass } @@ -826,7 +826,7 @@ data FamilyDecl pass = FamilyDecl , fdTopLevel :: TopLevelFlag -- used for printing only , fdLName :: LIdP pass -- type constructor , fdTyVars :: LHsQTyVars pass -- type variables - -- See Note [TyVar binders for associated declarations] + -- See Note [TyVar binders for associated decls] , fdFixity :: LexicalFixity -- Fixity used in the declaration , fdResultSig :: LFamilyResultSig pass -- result signature , fdInjectivityAnn :: Maybe (LInjectivityAnn pass) -- optional injectivity ann diff --git a/compiler/Language/Haskell/Syntax/Expr.hs b/compiler/Language/Haskell/Syntax/Expr.hs index 418aa59f84..049d511318 100644 --- a/compiler/Language/Haskell/Syntax/Expr.hs +++ b/compiler/Language/Haskell/Syntax/Expr.hs @@ -1508,7 +1508,7 @@ In any other context than 'MonadComp', the fields for most of these Note [Applicative BodyStmt] - +~~~~~~~~~~~~~~~~~~~~~~~~~~~ (#12143) For the purposes of ApplicativeDo, we treat any BodyStmt as if it was a BindStmt with a wildcard pattern. For example, diff --git a/compiler/Language/Haskell/Syntax/Type.hs b/compiler/Language/Haskell/Syntax/Type.hs index 173b75c4c2..10c2c03b48 100644 --- a/compiler/Language/Haskell/Syntax/Type.hs +++ b/compiler/Language/Haskell/Syntax/Type.hs @@ -1261,6 +1261,7 @@ instance (Outputable tm, Outputable ty) => Outputable (HsArg tm ty) where ppr (HsArgPar sp) = text "HsArgPar" <+> ppr sp {- Note [HsArgPar] +~~~~~~~~~~~~~~~ A HsArgPar indicates that everything to the left of this in the argument list is enclosed in parentheses together with the function itself. It is necessary so that we can recreate the parenthesis structure in the original source after |