Haddock: Fix very confusing formatting errors (#2622)

Because of mistakes escaping special characters, some documentation
showed the operators `$` and `*` where the Functor and Applicative
operators were intended. Since they are all very common operators, this
can be very confusing to the reader.

Additionally, it was discovered that later versions of Haddock start
interpreting Markdown-style links in code blocks, breaking the
rendering of the primitive blackboxes in `Clash.Tutorial`. This problem
does not occur with GHC 9.0.2 (Haddock 2.25.1), which we use to build
the documentation for Hackage. But it does occur with at least GHC 9.6.

To make such things less problematic, we decided to use bird tracks
(lines starting with '> ') for code blocks that are not Haskell code,
and only use the '@...@' style of code block for Haskell code. Bird
tracks don't use any formatting at all. All code blocks with something
other than Haskell code have been converted to bird tracks.
Additionally, some escaping issues in Haskell code blocks were fixed
when they were noticed.

Author: DigitalBrains1

clash-cosim/src/Clash/CoSim/DSLParser.hs

@@ -129,11 +129,9 @@ dslParser =
 -- The parser will detect a module name if it is mentioned as the first thing
 -- followed by at least three dashes on the following line. For example:
 --
--- @
--- MODULE: my_module_name
--- ----------
--- <!-- HDL code starts here -->
--- @
+-- > MODULE: my_module_name
+-- > ----------
+-- > <!-- HDL code starts here -->
 parse
     :: String
     -> Either ParseError (Maybe String, CoSimDSL)

clash-ffi/src/Clash/FFI/VPI/Object/Value/Parse.hs

@@ -84,9 +84,7 @@ parseBinStr bitSize bin = do
 --
 -- Consider the following bit string:
 --
---   @
---   9'b.0.1.1001
---   @
+-- > 9'b.0.1.1001
 --
 -- Attempting to read this as octal or hexadecimal results in a loss of
 -- precision in the value, giving @XX1@ and @xX9@. When @\'X\'@ (or @\'Z\'@)

clash-lib/src/Clash/Netlist/Util.hs

@@ -1168,15 +1168,13 @@ declareUseOnce u i = usageMap %= Map.alter go (Id.toText i)
 -- | Declare uses which occur as a result of a component being instantiated,
 -- for example the following design (verilog)
 --
---    @
---    module f ( input p; output reg r ) ... endmodule
---
---    module top ( ... )
---      ...
---      f f_inst ( .p(p), .r(foo));
---      ...
---    endmodule
---    @
+-- > module f ( input p; output reg r ) ... endmodule
+-- >
+-- > module top ( ... )
+-- >   ...
+-- >   f f_inst ( .p(p), .r(foo));
+-- >   ...
+-- > endmodule
 --
 -- would declare a usage of foo, since it is assigned by @f_inst@.
 --

clash-lib/src/Clash/Normalize/Transformations/Case.hs

@@ -454,18 +454,20 @@ matchLiteralContructor c _ _ =
 
 -- | Remove non-reachable alternatives. For example, consider:
 --
---    data STy ty where
---      SInt :: Int -> STy Int
---      SBool :: Bool -> STy Bool
+-- @
+-- data STy ty where
+--   SInt :: Int -> STy Int
+--   SBool :: Bool -> STy Bool
 --
---    f :: STy ty -> ty
---    f (SInt b) = b + 1
---    f (SBool True) = False
---    f (SBool False) = True
---    {-# NOINLINE f #-}
+-- f :: STy ty -> ty
+-- f (SInt b) = b + 1
+-- f (SBool True) = False
+-- f (SBool False) = True
+-- {\-\# NOINLINE f \#-\}
 --
---    g :: STy Int -> Int
---    g = f
+-- g :: STy Int -> Int
+-- g = f
+-- @
 --
 -- @f@ is always specialized on @STy Int@. The SBool alternatives are therefore
 -- unreachable. Additional information can be found at:
@@ -498,7 +500,7 @@ caseElemNonReachable _ e = return e
 -- GHC generates Core that looks like:
 --
 -- @
--- f = \(x :: Unsigned 4) -> case x == fromInteger 3 of
+-- f = \\(x :: Unsigned 4) -> case x == fromInteger 3 of
 --                             False -> case x == fromInteger 2 of
 --                               False -> case x == fromInteger 1 of
 --                                 False -> case x == fromInteger 0 of
@@ -515,7 +517,7 @@ caseElemNonReachable _ e = return e
 -- This transformation transforms the above Core to the saner:
 --
 -- @
--- f = \(x :: Unsigned 4) -> case x of
+-- f = \\(x :: Unsigned 4) -> case x of
 --        _ -> error "incomplete case"
 --        0 -> fromInteger 3
 --        1 -> fromInteger 2

clash-lib/src/Clash/Normalize/Transformations/Cast.hs

@@ -42,7 +42,7 @@ import Clash.Util (ClashException(..), curLoc)
 -- transforms to:
 -- @
 --   y = f' a
---     where f' x' = (\x -> g x) (cast x')
+--     where f' x' = (\\x -> g x) (cast x')
 -- @
 --
 -- The reason d'etre for this transformation is that we hope to end up with

clash-lib/src/Clash/Normalize/Transformations/MultiPrim.hs

@@ -58,7 +58,7 @@ import Clash.Rewrite.Util (changed)
 -- will be rewritten to:
 --
 -- @
---   \(x :: a) ->
+--   \\(x :: a) ->
 --         let
 --            r  = prim @a @b @c x r0 r1 -- With 'Clash.Core.Term.MultiPrim'
 --            r0 = c$multiPrimSelect r0 r

clash-lib/src/Clash/Normalize/Transformations/Specialize.hs

@@ -141,7 +141,7 @@ import Clash.Util (ClashException(..))
 -- Imagine
 --
 -- @
--- (\x -> e) u
+-- (\\x -> e) u
 -- @
 --
 -- where @u@ has a free variable named @x@, rewriting this to:

clash-lib/src/Clash/Primitives/DSL.hs

@@ -842,14 +842,12 @@ instHO bbCtx fPos (resTy, bbResTy) argsWithTypes = do
 --
 -- A typical result is that a
 --
--- @
--- component fifo port
---    ( rst : in std_logic
---    ...
---    ; full : out std_logic
---    ; empty : out std_logic );
---  end component;
--- @
+-- > component fifo port
+-- >    ( rst : in std_logic
+-- >    ...
+-- >    ; full : out std_logic
+-- >    ; empty : out std_logic );
+-- >  end component;
 --
 -- declaration would be added in the appropriate place.
 compInBlock
@@ -1068,9 +1066,7 @@ notExpr nm aExpr = do
 
 -- | Creates a BV that produces the following vhdl:
 --
--- @
---    (0 to n => ARG)
--- @
+-- > (0 to n => ARG)
 --
 -- TODO: Implement for (System)Verilog
 pureToBV
@@ -1090,9 +1086,7 @@ pureToBV nm n arg = do
 
 -- | Creates a BV that produces the following vhdl:
 --
--- @
---    std_logic_vector(resize(ARG, n))
--- @
+-- > std_logic_vector(resize(ARG, n))
 --
 -- TODO: Implement for (System)Verilog
 pureToBVResized

clash-prelude/src/Clash/Annotations/Primitive.hs

@@ -201,10 +201,8 @@ data HDL
 --
 -- You create a package which has a @myfancyip.cabal@ file with the following stanza:
 --
--- @
--- data-files: path\/to\/MyFancyIP.primitives
--- cpp-options: -DCABAL
--- @
+-- > data-files: path/to/MyFancyIP.primitives
+-- > cpp-options: -DCABAL
 --
 -- and a @MyFancyIP.hs@ module with the simulation definition and primitive.
 --

clash-prelude/src/Clash/Annotations/SynthesisAttributes.hs

@@ -41,11 +41,9 @@ type Annotate (a :: Type) (attrs :: k) = a
 -- | Synthesis attributes are directives passed to synthesis tools, such as
 -- Quartus. An example of such an attribute in VHDL:
 --
--- @
---   attribute chip_pin : string;
---   attribute chip_pin of sel : signal is \"C4\";
---   attribute chip_pin of data : signal is "D1, D2, D3, D4";
--- @
+-- > attribute chip_pin : string;
+-- > attribute chip_pin of sel : signal is "C4";
+-- > attribute chip_pin of data : signal is "D1, D2, D3, D4";
 --
 -- This would instruct the synthesis tool to map the wire /sel/ to pin /C4/, and
 -- wire /data/ to pins /D1/, /D2/, /D3/, and /D4/. To achieve this in Clash, /Attr/s
@@ -92,7 +90,7 @@ type Annotate (a :: Type) (attrs :: k) = a
 -- @
 -- f :: Signal System Bool \`Annotate\` 'StringAttr \"chip_pin\" \"C4\"
 --   -> Signal System Bool
--- f x = id x -- Using a lambda, i.e. f = \x -> id x also works
+-- f x = id x -- Using a lambda, i.e. f = \\x -> id x also works
 -- @
 --
 -- will reliably show the annotation in the generated HDL, but