Fix a few Note inconsistencies

40 files changed, 69 insertions, 80 deletions

diff --git a/libraries/base/Control/Concurrent/QSem.hs b/libraries/base/Control/Concurrent/QSem.hs
index 9f53eef826..08524323e2 100644
--- a/libraries/base/Control/Concurrent/QSem.hs
+++ b/libraries/base/Control/Concurrent/QSem.hs
@@ -100,7 +100,7 @@ signalQSem (QSem m) =
     putMVar m r'
 
 -- Note [signal uninterruptible]
---
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 --   If we have
 --
 --      bracket waitQSem signalQSem (...)
diff --git a/libraries/base/Control/Monad.hs b/libraries/base/Control/Monad.hs
index 86c15daf00..d2d0e29e43 100644
--- a/libraries/base/Control/Monad.hs
+++ b/libraries/base/Control/Monad.hs
@@ -222,7 +222,7 @@ zipWithM f xs ys  =  sequenceA (zipWith f xs ys)
 zipWithM_         :: (Applicative m) => (a -> b -> m c) -> [a] -> [b] -> m ()
 {-# INLINE zipWithM_ #-}
 -- Inline so that fusion with zipWith and sequenceA have a chance to fire
--- See Note [Fusion for zipN/zipWithN] in List.hs]
+-- See Note [Fusion for zipN/zipWithN] in List.hs.
 zipWithM_ f xs ys =  sequenceA_ (zipWith f xs ys)
 
 {- | The 'foldM' function is analogous to 'Data.Foldable.foldl', except that its result is
@@ -262,7 +262,6 @@ foldM_ f a xs  = foldlM f a xs >> return ()
 {-
 Note [Worker/wrapper transform on replicateM/replicateM_]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 The implementations of replicateM and replicateM_ both leverage the
 worker/wrapper transform. The simpler implementation of replicateM_, as an
 example, would be:
diff --git a/libraries/base/Control/Monad/ST/Imp.hs b/libraries/base/Control/Monad/ST/Imp.hs
index cbcee8dd90..9658fbd635 100644
--- a/libraries/base/Control/Monad/ST/Imp.hs
+++ b/libraries/base/Control/Monad/ST/Imp.hs
@@ -62,7 +62,6 @@ fixST k = unsafeIOToST $ do
 
 {- Note [fixST]
    ~~~~~~~~~~~~
-
 For many years, we implemented fixST much like a pure fixpoint,
 using liftST:
 
diff --git a/libraries/base/Control/Monad/ST/Lazy/Imp.hs b/libraries/base/Control/Monad/ST/Lazy/Imp.hs
index de8310c76d..888839132e 100644
--- a/libraries/base/Control/Monad/ST/Lazy/Imp.hs
+++ b/libraries/base/Control/Monad/ST/Lazy/Imp.hs
@@ -68,7 +68,7 @@ newtype ST s a = ST { unST :: State s -> (a, State s) }
 data State s = S# (State# s)
 
 {- Note [Lazy ST and multithreading]
-
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 We used to imagine that passing a polymorphic state token was all that we
 needed to keep state threads separate (see Launchbury and Peyton Jones, 1994:
 https://www.microsoft.com/en-us/research/publication/lazy-functional-state-threads/).
@@ -87,7 +87,7 @@ one we get from the previous computation, and the unlifted one we pull out of
 thin air. -}
 
 {- Note [Lazy ST: not producing lazy pairs]
-
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The fixST and strictToLazyST functions used to construct functions that
 produced lazy pairs. Why don't we need that laziness? The ST type is kept
 abstract, so no one outside this module can ever get their hands on a (result,
diff --git a/libraries/base/Data/OldList.hs b/libraries/base/Data/OldList.hs
index 2a50de3ee5..5ffdd84ad3 100644
--- a/libraries/base/Data/OldList.hs
+++ b/libraries/base/Data/OldList.hs
@@ -1361,6 +1361,7 @@ singleton x = [x]
 --
 
 -- Note [INLINE unfoldr]
+-- ~~~~~~~~~~~~~~~~~~~~~
 -- We treat unfoldr a little differently from some other forms for list fusion
 -- for two reasons:
 --
diff --git a/libraries/base/Data/Typeable/Internal.hs b/libraries/base/Data/Typeable/Internal.hs
index 13853c9301..e9cb1a1937 100644
--- a/libraries/base/Data/Typeable/Internal.hs
+++ b/libraries/base/Data/Typeable/Internal.hs
@@ -275,7 +275,6 @@ having to walk their full structures.
 
 {- Note [Kind caching]
    ~~~~~~~~~~~~~~~~~~~
-
 We cache the kind of the TypeRep in each TrTyCon and TrApp constructor.
 This is necessary to ensure that typeRepKind (which is used, at least, in
 deserialization and dynApply) is cheap. There are two reasons for this:
diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index 21ad469d27..bf1527076c 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -150,7 +150,6 @@ default ()              -- Double isn't available yet
 {-
 Note [Depend on GHC.Num.Integer]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 The Integer type is special because GHC.CoreToStg.Prep.mkConvertNumLiteral
 lookups names in ghc-bignum interfaces to construct Integer literal values.
 Currently it reads the interface file whether or not the current module *has*
diff --git a/libraries/base/GHC/Bits.hs b/libraries/base/GHC/Bits.hs
index 012550a60b..201340f348 100644
--- a/libraries/base/GHC/Bits.hs
+++ b/libraries/base/GHC/Bits.hs
@@ -668,8 +668,9 @@ isBitSubType x y
     ySigned = isSigned     y
 {-# INLINE isBitSubType #-}
 
-{-      Note [Constant folding for rotate]
-        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{-
+Note [Constant folding for rotate]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The INLINE on the Int instance of rotate enables it to be constant
 folded.  For example:
      sumU . mapU (`rotate` 3) . replicateU 10000000 $ (7 :: Int)
diff --git a/libraries/base/GHC/Enum.hs b/libraries/base/GHC/Enum.hs
index 5c184256f4..d80689423c 100644
--- a/libraries/base/GHC/Enum.hs
+++ b/libraries/base/GHC/Enum.hs
@@ -179,7 +179,6 @@ boundedEnumFromThen n1 n2
 {-
 Note [Stable Unfolding for list producers]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 The INLINABLE/INLINE pragmas ensure that we export stable (unoptimised)
 unfoldings in the interface file so we can do list fusion at usage sites.
 -}
@@ -892,6 +891,7 @@ instance  Enum Integer  where
  #-}
 
 {- Note [Enum Integer rules for literal 1]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The "1" rules above specialise for the common case where delta = 1,
 so that we can avoid the delta>=0 test in enumDeltaToIntegerFB.
 Then enumDeltaToInteger1FB is nice and small and can be inlined,
diff --git a/libraries/base/GHC/Event/Windows.hsc b/libraries/base/GHC/Event/Windows.hsc
index 973f25722b..97a224fdc7 100644
--- a/libraries/base/GHC/Event/Windows.hsc
+++ b/libraries/base/GHC/Event/Windows.hsc
@@ -495,9 +495,8 @@ associateHandle Manager{..} h =
       FFI.associateHandleWithIOCP mgrIOCP h (fromIntegral $ ptrToWordPtr h)
 
 
-{- Note [Why use non-waiting getOverlappedResult requests.]
-   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+{- Note [Why use non-waiting getOverlappedResult requests]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   When waiting for a request that is bound to be done soon
   we spin inside waitForCompletion. There are multiple reasons
   for this.
@@ -549,6 +548,7 @@ withOverlappedEx mgr fname h async offset startCB completionCB = do
               IOFailed  err -> signalThrow err
 
       -- Note [Memory Management]
+      -- ~~~~~~~~~~~~~~~~~~~~~~~~
       -- These callback data and especially the overlapped structs have to keep
       -- alive throughout the entire lifetime of the requests.   Since this
       -- function will block until done so it can call completionCB at the end
diff --git a/libraries/base/GHC/Event/Windows/FFI.hsc b/libraries/base/GHC/Event/Windows/FFI.hsc
index c087f94eb1..e6ae168d3f 100644
--- a/libraries/base/GHC/Event/Windows/FFI.hsc
+++ b/libraries/base/GHC/Event/Windows/FFI.hsc
@@ -136,6 +136,7 @@ foreign import WINDOWS_CCONV safe "windows.h GetQueuedCompletionStatusEx"
                                   -> Ptr ULONG -> DWORD -> BOOL -> IO BOOL
 
 -- | Note [Completion Ports]
+--   ~~~~~~~~~~~~~~~~~~~~~~~
 -- When an I/O operation has been queued by an operation
 -- (ReadFile/WriteFile/etc) it is placed in a queue that the driver uses when
 -- servicing IRQs.  This queue has some important properties:
@@ -343,7 +344,8 @@ pokeEventOverlapped lpol event = do
 ------------------------------------------------------------------------
 -- Request management
 
--- [Note AsyncHandles]
+-- Note [AsyncHandles]
+-- ~~~~~~~~~~~~~~~~~~~
 -- In `winio` we have designed it to work in asynchronous mode always.
 -- According to the MSDN documentation[1][2], when a handle is not opened
 -- in asynchronous mode then the operation would simply work but operate
@@ -392,7 +394,7 @@ pokeEventOverlapped lpol event = do
 --    invalid.  This is an issue because to pass `HANDLE`s we have to pass
 --    the native OS Handle not the Haskell one. i.e. remote-iserv.
 
--- See [Note AsyncHandles]
+-- See Note [AsyncHandles]
 withRequest :: Bool -> Word64 -> HANDLE -> IOCallback
             -> (Ptr HASKELL_OVERLAPPED -> Ptr CompletionData -> IO a)
             -> IO a
diff --git a/libraries/base/GHC/Foreign.hs b/libraries/base/GHC/Foreign.hs
index 658f5c3515..042745ce11 100644
--- a/libraries/base/GHC/Foreign.hs
+++ b/libraries/base/GHC/Foreign.hs
@@ -295,7 +295,6 @@ tryFillBuffer encoder null_terminate from0 to_p to_sz_bytes = do
 {-
 Note [Check *before* fill in withEncodedCString]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 It's very important that the size check and readjustment peformed by tryFillBuffer
 happens before the continuation is called. The size check is the part which can
 fail, the call to the continuation never fails and so the caller should respond
diff --git a/libraries/base/GHC/ForeignPtr.hs b/libraries/base/GHC/ForeignPtr.hs
index a7061152dc..0361857bcc 100644
--- a/libraries/base/GHC/ForeignPtr.hs
+++ b/libraries/base/GHC/ForeignPtr.hs
@@ -165,7 +165,7 @@ data ForeignPtrContents
     -- The invariants that apply to 'MallocPtr' apply to 'PlainPtr' as well.
 
 -- Note [Why FinalPtr]
---
+-- ~~~~~~~~~~~~~~~~~~~
 -- FinalPtr exists as an optimization for foreign pointers created
 -- from Addr# literals. Most commonly, this happens in the bytestring
 -- library, where the combination of OverloadedStrings and a rewrite
@@ -376,7 +376,9 @@ addForeignPtrFinalizer (FunPtr fp) (ForeignPtr p c) = case c of
   MallocPtr     _ r -> insertCFinalizer r fp 0# nullAddr# p c
   _ -> errorWithoutStackTrace "GHC.ForeignPtr: attempt to add a finalizer to a plain pointer or a final pointer"
 
--- Note [MallocPtr finalizers] (#10904)
+-- Note [MallocPtr finalizers]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- Ticket: #10904
 --
 -- When we have C finalizers for a MallocPtr, the memory is
 -- heap-resident and would normally be recovered by the GC before the
diff --git a/libraries/base/GHC/IO/Encoding/Failure.hs b/libraries/base/GHC/IO/Encoding/Failure.hs
index 271d66b35f..a26e3f8fcc 100644
--- a/libraries/base/GHC/IO/Encoding/Failure.hs
+++ b/libraries/base/GHC/IO/Encoding/Failure.hs
@@ -58,7 +58,6 @@ data CodingFailureMode
 
 -- Note [Roundtripping]
 -- ~~~~~~~~~~~~~~~~~~~~
---
 -- Roundtripping is based on the ideas of PEP383.
 --
 -- We used to use the range of private-use characters from 0xEF80 to
diff --git a/libraries/base/GHC/IO/FD.hs b/libraries/base/GHC/IO/FD.hs
index 9e9fa428b8..e97229704c 100644
--- a/libraries/base/GHC/IO/FD.hs
+++ b/libraries/base/GHC/IO/FD.hs
@@ -537,8 +537,8 @@ fdWriteNonBlocking fd ptr _offset bytes = do
 #if !defined(mingw32_HOST_OS)
 
 {-
-NOTE [nonblock]:
-
+Note [nonblock]
+~~~~~~~~~~~~~~~
 Unix has broken semantics when it comes to non-blocking I/O: you can
 set the O_NONBLOCK flag on an FD, but it applies to the all other FDs
 attached to the same underlying file, pipe or TTY; there's no way to
diff --git a/libraries/base/GHC/IO/Handle/Internals.hs b/libraries/base/GHC/IO/Handle/Internals.hs
index 1bdb47b7ca..cbd43c1666 100644
--- a/libraries/base/GHC/IO/Handle/Internals.hs
+++ b/libraries/base/GHC/IO/Handle/Internals.hs
@@ -188,7 +188,7 @@ do_operation fun h act m = do
             throwIO e
 
 -- Note [async]
---
+-- ~~~~~~~~~~~~
 -- If an asynchronous exception is raised during an I/O operation,
 -- normally it is fine to just re-throw the exception synchronously.
 -- However, if we are inside an unsafePerformIO or an
@@ -644,7 +644,6 @@ flushByteReadBuffer h_@Handle__{..} = do
 
 {- Note [Making offsets for append]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
   The WINIO subysstem keeps track of offsets for handles
   on the Haskell side of things instead of letting the OS
   handle it. This requires us to establish the correct offset
diff --git a/libraries/base/GHC/IO/Handle/Text.hs b/libraries/base/GHC/IO/Handle/Text.hs
index bb576bcfd1..0e3dcd709e 100644
--- a/libraries/base/GHC/IO/Handle/Text.hs
+++ b/libraries/base/GHC/IO/Handle/Text.hs
@@ -320,7 +320,7 @@ unpack_nl !buf !r !w acc0
                 return (str, w)
 
 -- Note [#5536]
---
+-- ~~~~~~~~~~~~
 -- We originally had
 --
 --    let c' = desurrogatifyRoundtripCharacter c in
diff --git a/libraries/base/GHC/IO/Unsafe.hs b/libraries/base/GHC/IO/Unsafe.hs
index e6c43e920c..98d2e12345 100644
--- a/libraries/base/GHC/IO/Unsafe.hs
+++ b/libraries/base/GHC/IO/Unsafe.hs
@@ -27,8 +27,9 @@ module GHC.IO.Unsafe (
 
 import GHC.Base
 
-{- Note [unsafePerformIO and strictness]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{-
+Note [unsafePerformIO and strictness]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Consider this sub-expression (from tests/lib/should_run/memo002)
 
  unsafePerformIO (do { lockMemoTable
diff --git a/libraries/base/GHC/IO/Windows/Handle.hsc b/libraries/base/GHC/IO/Windows/Handle.hsc
index bee7bc73a2..784a08f9d2 100644
--- a/libraries/base/GHC/IO/Windows/Handle.hsc
+++ b/libraries/base/GHC/IO/Windows/Handle.hsc
@@ -526,6 +526,7 @@ hwndWriteNonBlocking hwnd ptr offset bytes
         | otherwise                        = Mgr.ioFailed err
 
 -- Note [ReadFile/WriteFile]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~
 -- The results of these functions are somewhat different when working in an
 -- asynchronous manner. The returning bool has two meaning.
 --
diff --git a/libraries/base/GHC/IORef.hs b/libraries/base/GHC/IORef.hs
index 616950c3c0..db932fca90 100644
--- a/libraries/base/GHC/IORef.hs
+++ b/libraries/base/GHC/IORef.hs
@@ -127,7 +127,6 @@ atomicModifyIORef' ref f = do
 
 -- Note [atomicModifyIORef' definition]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- atomicModifyIORef' was historically defined
 --
 --    atomicModifyIORef' ref f = do
diff --git a/libraries/base/GHC/Int.hs b/libraries/base/GHC/Int.hs
index a514f4d35b..bde52848fd 100644
--- a/libraries/base/GHC/Int.hs
+++ b/libraries/base/GHC/Int.hs
@@ -160,13 +160,13 @@ instance Integral Int8 where
         | otherwise                  = I8# (x# `modInt8#` y#)
     quotRem x@(I8# x#) y@(I8# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case x# `quotRemInt8#` y# of
                                        (# q, r #) -> (I8# q, I8# r)
     divMod  x@(I8# x#) y@(I8# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case  x# `divModInt8#` y# of
                                        (# d, m #) -> (I8# d, I8# m)
@@ -371,13 +371,13 @@ instance Integral Int16 where
         | otherwise                  = I16# (x# `modInt16#` y#)
     quotRem x@(I16# x#) y@(I16# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case x# `quotRemInt16#` y# of
                                        (# q, r #) -> (I16# q, I16# r)
     divMod  x@(I16# x#) y@(I16# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case x# `divModInt16#` y# of
                                        (# d, m #) -> (I16# d, I16# m)
@@ -579,13 +579,13 @@ instance Integral Int32 where
         | otherwise                  = I32# (x# `modInt32#` y#)
     quotRem x@(I32# x#) y@(I32# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case x# `quotRemInt32#` y# of
                                        (# q, r #) -> (I32# q, I32# r)
     divMod  x@(I32# x#) y@(I32# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
         | otherwise                  = case x# `divModInt32#` y# of
                                        (# d, m #) -> (I32# d, I32# m)
@@ -779,7 +779,7 @@ instance Enum Int64 where
 instance Integral Int64 where
     quot    x@(I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
-        | y == (-1) && x == minBound = overflowError -- Note [Order of tests]
+        | y == (-1) && x == minBound = overflowError -- See Note [Order of tests]
         | otherwise                  = I64# (x# `quotInt64#` y#)
     rem       (I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
@@ -791,7 +791,7 @@ instance Integral Int64 where
         | otherwise                  = I64# (x# `remInt64#` y#)
     div     x@(I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
-        | y == (-1) && x == minBound = overflowError -- Note [Order of tests]
+        | y == (-1) && x == minBound = overflowError -- See Note [Order of tests]
         | otherwise                  = I64# (x# `divInt64#` y#)
     mod       (I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
@@ -803,7 +803,7 @@ instance Integral Int64 where
         | otherwise                  = I64# (x# `modInt64#` y#)
     quotRem x@(I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
 #if WORD_SIZE_IN_BITS < 64
         -- we don't have quotRemInt64# primop yet
@@ -814,7 +814,7 @@ instance Integral Int64 where
 #endif
     divMod  x@(I64# x#) y@(I64# y#)
         | y == 0                     = divZeroError
-          -- Note [Order of tests]
+          -- See Note [Order of tests]
         | y == (-1) && x == minBound = (overflowError, 0)
 #if WORD_SIZE_IN_BITS < 64
         -- we don't have divModInt64# primop yet
@@ -952,8 +952,9 @@ instance Ix Int64 where
 
 -------------------------------------------------------------------------------
 
-{- Note [Order of tests]
-~~~~~~~~~~~~~~~~~~~~~~~~~
+{-
+Note [Order of tests]
+~~~~~~~~~~~~~~~~~~~~~
 (See #3065, #5161.) Suppose we had a definition like:
 
     quot x y
diff --git a/libraries/base/GHC/List.hs b/libraries/base/GHC/List.hs
index 677d0fe7c1..8dc897c73c 100644
--- a/libraries/base/GHC/List.hs
+++ b/libraries/base/GHC/List.hs
@@ -284,7 +284,7 @@ foldl k z0 xs =
 
 {-
 Note [Left folds via right fold]
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Implementing foldl et. al. via foldr is only a good idea if the compiler can
 optimize the resulting code (eta-expand the recursive "go"). See #7994.
 We hope that one of the two measure kick in:
@@ -309,7 +309,7 @@ inline FB functions because:
 * They are higher-order functions and therefore benefit from inlining.
 
 * When the final consumer is a left fold, inlining the FB functions is the only
-  way to make arity expansion happen. See Note [Left fold via right fold].
+  way to make arity expansion happen. See Note [Left folds via right fold].
 
 For this reason we mark all FB functions INLINE [0]. The [0] phase-specifier
 ensures that calls to FB functions can be written back to the original form
@@ -458,7 +458,7 @@ scanl                   = scanlGo
                                []   -> []
                                x:xs -> scanlGo f (f q x) xs)
 
--- Note [scanl rewrite rules]
+-- See Note [scanl rewrite rules]
 {-# RULES
 "scanl"  [~1] forall f a bs . scanl f a bs =
   build (\c n -> a `c` foldr (scanlFB f c) (constScanl n) bs a)
@@ -509,7 +509,7 @@ scanl' = scanlGo'
                             []   -> []
                             x:xs -> scanlGo' f (f q x) xs)
 
--- Note [scanl rewrite rules]
+-- See Note [scanl rewrite rules]
 {-# RULES
 "scanl'"  [~1] forall f a bs . scanl' f a bs =
   build (\c n -> a `c` foldr (scanlFB' f c) (flipSeqScanl' n) bs a)
@@ -529,7 +529,6 @@ flipSeqScanl' a !_b = a
 {-
 Note [scanl rewrite rules]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 In most cases, when we rewrite a form to one that can fuse, we try to rewrite it
 back to the original form if it does not fuse. For scanl, we do something a
 little different. In particular, we rewrite
@@ -651,7 +650,9 @@ scanrFB f c = \x ~(r, est) -> (f x r, r `c` est)
                  scanr f q0 ls
  #-}
 
-{- Note [scanrFB and evaluation]
+{-
+Note [scanrFB and evaluation]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In a previous Version, the pattern match on the tuple in scanrFB used to be
 strict. If scanr is called with a build expression, the following would happen:
 The rule "scanr" would fire, and we obtain
@@ -1417,8 +1418,9 @@ foldr3_left _  z _ _  _      _     = z
                   foldr3 k z (build g) = g (foldr3_left k z) (\_ _ -> z)
  #-}
 
-{- Note [Fusion for foldrN]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{-
+Note [Fusion for foldrN]
+~~~~~~~~~~~~~~~~~~~~~~~~
 We arrange that foldr2, foldr3, etc is a good consumer for its first
 (left) list argument. Here's how. See below for the second, third
 etc list arguments
diff --git a/libraries/base/GHC/Read.hs b/libraries/base/GHC/Read.hs
index 7f698ec498..2c9aec08cd 100644
--- a/libraries/base/GHC/Read.hs
+++ b/libraries/base/GHC/Read.hs
@@ -410,7 +410,7 @@ readSymField fieldName readVal = do
 
 
 -- Note [Why readField]
---
+-- ~~~~~~~~~~~~~~~~~~~~
 -- Previously, the code for automatically deriving Read instance (in
 -- typecheck/GHC.Tc.Deriv.Generate.hs) would generate inline code for parsing fields;
 -- this, however, turned out to produce massive amounts of intermediate code,
diff --git a/libraries/base/GHC/Real.hs b/libraries/base/GHC/Real.hs
index d970a3e1ed..e8cfbfbc57 100644
--- a/libraries/base/GHC/Real.hs
+++ b/libraries/base/GHC/Real.hs
@@ -301,7 +301,7 @@ numericEnumFromThenTo e1 e2 e3
                                            | otherwise = (>= e3 + mid)
 
 {- Note [Numeric Stability of Enumerating Floating Numbers]
------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 When enumerate floating numbers, we could add the increment to the last number
 at every run (as what we did previously):
 
diff --git a/libraries/base/GHC/TopHandler.hs b/libraries/base/GHC/TopHandler.hs
index ba86798091..6a4e0325a6 100644
--- a/libraries/base/GHC/TopHandler.hs
+++ b/libraries/base/GHC/TopHandler.hs
@@ -52,14 +52,13 @@ import Data.Dynamic (toDyn)
 
 -- Note [rts_setMainThread must be called unsafely]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- rts_setMainThread must be called as unsafe, because it
 -- dereferences the Weak# and manipulates the raw Haskell value
 -- behind it.  Therefore, it must not race with a garbage collection.
 
+
 -- Note [rts_setMainThread has an unsound type]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- 'rts_setMainThread' is imported with type Weak# ThreadId -> IO (),
 -- but this is an unsound type for it: it grabs the /key/ of the
 -- 'Weak#' object, which isn't tracked by the type at all.
@@ -212,9 +211,9 @@ disasterHandler exit _ =
         "encode an error message. Check that your locale is configured " ++
         "properly."
 
-{- Note [Disaster with iconv]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+{-
+Note [Disaster with iconv]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 When using iconv, it's possible for things like iconv_open to fail in
 restricted environments (like an initram or restricted container), but
 when this happens the error raised inevitably calls `peekCString`,
diff --git a/libraries/base/GHC/TypeNats.hs b/libraries/base/GHC/TypeNats.hs
index 4325f3a8bf..ef4a5a8817 100644
--- a/libraries/base/GHC/TypeNats.hs
+++ b/libraries/base/GHC/TypeNats.hs
@@ -92,8 +92,9 @@ someNatVal :: Natural -> SomeNat
 someNatVal n = withSNat SomeNat (SNat n) Proxy
 {-# NOINLINE someNatVal #-} -- See Note [NOINLINE someNatVal]
 
-{- Note [NOINLINE someNatVal]
-
+{-
+Note [NOINLINE someNatVal]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 `someNatVal` converts a natural number to an existentially quantified
 dictionary for `KnownNat` (aka `SomeNat`).  The existential quantification
 is very important, as it captures the fact that we don't know the type
diff --git a/libraries/base/System/IO.hs b/libraries/base/System/IO.hs
index f831df6cb4..6e8c4308d1 100644
--- a/libraries/base/System/IO.hs
+++ b/libraries/base/System/IO.hs
@@ -434,7 +434,6 @@ fixIO k = do
 
 -- Note [Blackholing in fixIO]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- We do our own explicit black holing here, because GHC's lazy
 -- blackholing isn't enough.  In an infinite loop, GHC may run the IO
 -- computation a few times before it notices the loop, which is wrong.
diff --git a/libraries/base/Unsafe/Coerce.hs b/libraries/base/Unsafe/Coerce.hs
index 9504eb13e2..930514ce81 100644
--- a/libraries/base/Unsafe/Coerce.hs
+++ b/libraries/base/Unsafe/Coerce.hs
@@ -286,7 +286,7 @@ unsafeCoerce# :: forall (r1 :: RuntimeRep) (r2 :: RuntimeRep)
                         (a :: TYPE r1) (b :: TYPE r2).
                  a -> b
 unsafeCoerce# = error "GHC internal error: unsafeCoerce# not unfolded"
--- See (U10) of Note [Implementing unsafeCorece]
+-- See (U10) of Note [Implementing unsafeCoerce]
 -- The RHS is updated by Desugar.patchMagicDefns
 -- See Desugar Note [Wiring in unsafeCoerce#]
 
diff --git a/libraries/base/cbits/inputReady.c b/libraries/base/cbits/inputReady.c
index 46b5577cfc..3f636c6b28 100644
--- a/libraries/base/cbits/inputReady.c
+++ b/libraries/base/cbits/inputReady.c
@@ -168,7 +168,7 @@ fdReady(int fd, bool write, int64_t msecs, bool isSock)
     Time remaining = MSToTime(msecs);
 
     // Note [Guaranteed syscall time spent]
-    //
+    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     // The implementation ensures that if fdReady() is called with N `msecs`,
     // it will not return before an FD-polling syscall *returns*
     // with `endTime` having passed.
diff --git a/libraries/ghc-bignum/src/GHC/Num/Primitives.hs b/libraries/ghc-bignum/src/GHC/Num/Primitives.hs
index d286a8d933..a33fd68b23 100644
--- a/libraries/ghc-bignum/src/GHC/Num/Primitives.hs
+++ b/libraries/ghc-bignum/src/GHC/Num/Primitives.hs
@@ -598,7 +598,6 @@ ioBool (IO io) s = case io s of
 
 -- Note [ghc-bignum exceptions]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- `ghc-bignum` package can't depend on `base` package (it would create a cyclic
 -- dependency). Hence it can't import "Control.Exception" and throw exceptions
 -- the usual way. Instead it uses some wired-in functions from `ghc-prim` which
diff --git a/libraries/ghc-boot/GHC/BaseDir.hs b/libraries/ghc-boot/GHC/BaseDir.hs
index db470425c0..dbbf61d02e 100644
--- a/libraries/ghc-boot/GHC/BaseDir.hs
+++ b/libraries/ghc-boot/GHC/BaseDir.hs
@@ -2,7 +2,6 @@
 
 -- | Note [Base Dir]
 -- ~~~~~~~~~~~~~~~~~
---
 -- GHC's base directory or top directory containers miscellaneous settings and
 -- the package database.  The main compiler of course needs this directory to
 -- read those settings and read and write packages. ghc-pkg uses it to find the
@@ -12,6 +11,7 @@
 -- will expand `${top_dir}` inside strings so GHC doesn't need to know it's on
 -- installation location at build time. ghc-pkg also can expand those variables
 -- and so needs the top dir location to do that too.
+
 module GHC.BaseDir where
 
 import Prelude -- See Note [Why do we import Prelude here?]
diff --git a/libraries/ghc-prim/GHC/CString.hs b/libraries/ghc-prim/GHC/CString.hs
index 1edeecbbfa..680d3c8a39 100644
--- a/libraries/ghc-prim/GHC/CString.hs
+++ b/libraries/ghc-prim/GHC/CString.hs
@@ -135,9 +135,9 @@ Moreover, we want to make it CONLIKE, so that:
 All of this goes for unpackCStringUtf8# too.
 -}
 
-{- Note [Inlining of unpackFoldrCString]
+{-
+Note [Inlining of unpackFoldrCString]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Usually the unpack-list rule turns unpackFoldrCString# into unpackCString#
 It also has a BuiltInRule in PrelRules.hs:
      unpackFoldrCString# "foo" c (unpackFoldrCString# "baz" c n)
@@ -154,9 +154,8 @@ when looking at nofib.
 This is especially important for elem which then results in an
 allocation free loop.
 
-  Note [unpackCString# iterating over addr]
+Note [unpackCString# iterating over addr]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 When unpacking unpackCString# and friends repeatedly return a cons cell
 containing:
 * The current character we just unpacked.
@@ -175,7 +174,6 @@ the string and the current offset, saving a word for each character unpacked.
 
 This has the additional advantage the we can guarantee that only the
 increment will happen in the loop.
-
 -}
 
 unpackCString# :: Addr# -> [Char]
diff --git a/libraries/ghc-prim/GHC/Classes.hs b/libraries/ghc-prim/GHC/Classes.hs
index 13e9556864..aa1c1b2d8b 100644
--- a/libraries/ghc-prim/GHC/Classes.hs
+++ b/libraries/ghc-prim/GHC/Classes.hs
@@ -587,7 +587,6 @@ x# `divInt32#` y# = ((x# `plusInt32#` bias#) `quotInt32#` y#) `subInt32#` hard#
 
 -- Note [divInt# implementation]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- divInt# (truncated toward zero) is implemented with quotInt# (truncated
 -- toward negative infinity). They differ when inputs x and y have different signs:
 --  - x `rem` y has the sign of x and (x `quot` y)*y + (x `rem` y) == x
@@ -705,7 +704,6 @@ x# `modInt32#` y# = r# `plusInt32#` k#
 
 -- Note [modInt# implementation]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- Similarly to divInt# (see Note [divInt# implementation]), we can derive the
 -- branchless implementation of modInt# as follows:
 --
@@ -823,7 +821,6 @@ x# `divModInt32#` y# = case (x# `plusInt32#` bias#) `quotRemInt32#` y# of
 
 -- Note [divModInt# implementation]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- divModInt# is written by deriving the following code similarly to divInt# and
 -- modInt# (see Note [divInt# implementation] and Note [modInt#
 -- implementation]).
diff --git a/libraries/ghc-prim/GHC/Prim/Exception.hs b/libraries/ghc-prim/GHC/Prim/Exception.hs
index 592d597f44..9d496d397c 100644
--- a/libraries/ghc-prim/GHC/Prim/Exception.hs
+++ b/libraries/ghc-prim/GHC/Prim/Exception.hs
@@ -20,7 +20,6 @@ default () -- Double and Integer aren't available yet
 
 -- Note [Arithmetic exceptions]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- ghc-prim provides several functions to raise arithmetic exceptions
 -- (raiseDivZero, raiseUnderflow, raiseOverflow) that are wired-in the RTS.
 -- These exceptions are meant to be used by the package implementing arbitrary
diff --git a/libraries/ghc-prim/GHC/Prim/PtrEq.hs b/libraries/ghc-prim/GHC/Prim/PtrEq.hs
index 5cc3e511e6..ba58857868 100644
--- a/libraries/ghc-prim/GHC/Prim/PtrEq.hs
+++ b/libraries/ghc-prim/GHC/Prim/PtrEq.hs
@@ -45,7 +45,6 @@ default () -- Double and Integer aren't available yet
 
 {- Note [Pointer equality operations]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Many primitive types - such as Array#, ByteArray#, MVar#, ... - are boxed:
 they are represented by pointers to the underlying data. It is thus possible
 to directly compare these pointers for equality, as opposed to comparing
@@ -55,7 +54,7 @@ two arrays element-wise).
 To do this, GHC provides the primop reallyUnsafePtrEquality#, which is
 both levity-polymorphic and heterogeneous. As its name indicates, it is an
 unsafe operation which can yield unpredictable results, as explained in
-  Note [Pointer comparison operations] in primops.txt.pp
+Note [Pointer comparison operations] in primops.txt.pp
 
 For a more user-friendly interface, this module defines specialisations of
 the reallyUnsafePtrEquality# primop at various primitive types, such as
@@ -116,7 +115,6 @@ sameIOPort# = reallyUnsafePtrEquality#
 
 -- Note [Comparing stable names]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
 -- A StableName# is actually a pointer to a stable name object (SNO)
 -- containing an index into the stable name table (SNT). We
 -- used to compare StableName#s by following the pointers to the
diff --git a/libraries/ghc-prim/GHC/Types.hs b/libraries/ghc-prim/GHC/Types.hs
index 22e637af6e..eaffc5c6d0 100644
--- a/libraries/ghc-prim/GHC/Types.hs
+++ b/libraries/ghc-prim/GHC/Types.hs
@@ -84,7 +84,7 @@ This declaration is important for :info (->) command (issue #10145)
 
 -- | The regular function type
 type (->) = FUN 'Many
--- See Note [Linear Types] in Multiplicity
+-- See Note [Linear types] in Multiplicity
 
 {- *********************************************************************
 *                                                                      *
@@ -261,7 +261,6 @@ newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
 {-
 Note [Kind-changing of (~) and Coercible]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 (~) and Coercible are tricky to define. To the user, they must appear as
 constraints, but we cannot define them as such in Haskell. But we also cannot
 just define them only in GHC.Prim (like (->)), because we need a real module
diff --git a/libraries/ghc-prim/cbits/atomic.c b/libraries/ghc-prim/cbits/atomic.c
index af26e16268..2ac6d26e1f 100644
--- a/libraries/ghc-prim/cbits/atomic.c
+++ b/libraries/ghc-prim/cbits/atomic.c
@@ -110,7 +110,6 @@ hs_atomic_and64(StgWord x, StgWord64 val)
 
 // Note [__sync_fetch_and_nand usage]
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-//
 // The __sync_fetch_and_nand builtin is a bit of a disaster. It was introduced
 // in GCC long ago with silly semantics. Specifically:
 //
diff --git a/libraries/ghc-prim/cbits/bitrev.c b/libraries/ghc-prim/cbits/bitrev.c
index eecbfe5ac5..2fcbd192b3 100644
--- a/libraries/ghc-prim/cbits/bitrev.c
+++ b/libraries/ghc-prim/cbits/bitrev.c
@@ -3,7 +3,6 @@
 /*
 Note [Bit reversal primop]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 There are two main ways of reversing the bit order of a word: bit twiddling
 and using a lookup table.
 See [this excellent](https://stackoverflow.com/questions/746171/most-efficient-algorithm-for-bit-reversal-from-msb-lsb-to-lsb-msb-in-c this)
diff --git a/libraries/ghci/GHCi/TH.hs b/libraries/ghci/GHCi/TH.hs
index 723e966095..77ddd0ccc8 100644
--- a/libraries/ghci/GHCi/TH.hs
+++ b/libraries/ghci/GHCi/TH.hs
@@ -13,7 +13,7 @@ module GHCi.TH
   ) where
 
 {- Note [Remote Template Haskell]
-
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Here is an overview of how TH works with -fexternal-interpreter.
 
 Initialisation
diff --git a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
index f30bb0ef87..7446297762 100644
--- a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
+++ b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
@@ -2592,7 +2592,6 @@ data Con = NormalC Name [BangType]       -- ^ @C Int a@
 
 -- Note [GADT return type]
 -- ~~~~~~~~~~~~~~~~~~~~~~~
---
 -- The return type of a GADT constructor does not necessarily match the name of
 -- the data type:
 --