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.

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

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

@@ -62,11 +62,11 @@ module Blinker where
 import Clash.Prelude
 import Clash.Intel.ClockGen
 
--- Define a synthesis domain with a clock with a period of 20000 /ps/. Signal
+-- Define a synthesis domain with a clock with a period of 20000 \/ps\/. Signal
 -- coming from the reset button is low when pressed, and high when not pressed.
 'Clash.Explicit.Signal.createDomain'
   vSystem{vName=\"DomInput\", vPeriod=20000, vResetPolarity=ActiveLow}
--- Define a synthesis domain with a clock with a period of 50000 /ps/.
+-- Define a synthesis domain with a clock with a period of 50000 \/ps\/.
 'Clash.Explicit.Signal.createDomain' vSystem{vName=\"Dom50\", vPeriod=50000}
 
 topEntity
@@ -117,31 +117,29 @@ blinkerT (leds,mode,cntr) key1R = ((leds',mode',cntr'),leds)
 The Clash compiler would normally generate the following
 @topEntity.vhdl@ file:
 
-@
--- Automatically generated VHDL-93
-library IEEE;
-use IEEE.STD_LOGIC_1164.ALL;
-use IEEE.NUMERIC_STD.ALL;
-use IEEE.MATH_REAL.ALL;
-use std.textio.all;
-use work.all;
-use work.Blinker_topEntity_types.all;
-
-entity topEntity is
-  port(-- clock
-       clk20   : in Blinker_topEntity_types.clk_DomInput;
-       -- reset
-       rstBtn  : in Blinker_topEntity_types.rst_DomInput;
-       -- enable
-       enaBtn  : in Blinker_topEntity_types.en_Dom50;
-       modeBtn : in std_logic;
-       result  : out std_logic_vector(7 downto 0));
-end;
-
-architecture structural of topEntity is
-  ...
-end;
-@
+> -- Automatically generated VHDL-93
+> library IEEE;
+> use IEEE.STD_LOGIC_1164.ALL;
+> use IEEE.NUMERIC_STD.ALL;
+> use IEEE.MATH_REAL.ALL;
+> use std.textio.all;
+> use work.all;
+> use work.Blinker_topEntity_types.all;
+>
+> entity topEntity is
+>   port(-- clock
+>        clk20   : in Blinker_topEntity_types.clk_DomInput;
+>        -- reset
+>        rstBtn  : in Blinker_topEntity_types.rst_DomInput;
+>        -- enable
+>        enaBtn  : in Blinker_topEntity_types.en_Dom50;
+>        modeBtn : in std_logic;
+>        result  : out std_logic_vector(7 downto 0));
+> end;
+>
+> architecture structural of topEntity is
+>   ...
+> end;
 
 However, if we add the following 'Synthesize' annotation in the file:
 
@@ -159,31 +157,29 @@ However, if we add the following 'Synthesize' annotation in the file:
 
 The Clash compiler will generate the following @blinker.vhdl@ file instead:
 
-@
--- Automatically generated VHDL-93
-library IEEE;
-use IEEE.STD_LOGIC_1164.ALL;
-use IEEE.NUMERIC_STD.ALL;
-use IEEE.MATH_REAL.ALL;
-use std.textio.all;
-use work.all;
-use work.blinker_types.all;
-
-entity blinker is
-  port(-- clock
-       CLOCK_50 : in blinker_types.clk_DomInput;
-       -- reset
-       KEY0     : in blinker_types.rst_DomInput;
-       -- enable
-       KEY1     : in blinker_types.en_Dom50;
-       KEY2     : in std_logic;
-       LED      : out std_logic_vector(7 downto 0));
-end;
-
-architecture structural of blinker is
-  ...
-end;
-@
+> -- Automatically generated VHDL-93
+> library IEEE;
+> use IEEE.STD_LOGIC_1164.ALL;
+> use IEEE.NUMERIC_STD.ALL;
+> use IEEE.MATH_REAL.ALL;
+> use std.textio.all;
+> use work.all;
+> use work.blinker_types.all;
+>
+> entity blinker is
+>   port(-- clock
+>        CLOCK_50 : in blinker_types.clk_DomInput;
+>        -- reset
+>        KEY0     : in blinker_types.rst_DomInput;
+>        -- enable
+>        KEY1     : in blinker_types.en_Dom50;
+>        KEY2     : in std_logic;
+>        LED      : out std_logic_vector(7 downto 0));
+> end;
+>
+> architecture structural of blinker is
+>   ...
+> end;
 
 Where we now have:
 
@@ -293,14 +289,12 @@ instance Lift TopEntity where
 --
 -- Clash would normally generate the following VHDL entity:
 --
--- @
--- entity f is
---   port(a      : in signed(63 downto 0);
---        b_0    : in signed(63 downto 0);
---        b_1    : in boolean;
---        result : out std_logic_vector(65 downto 0));
--- end;
--- @
+-- > entity f is
+-- >   port(a      : in signed(63 downto 0);
+-- >        b_0    : in signed(63 downto 0);
+-- >        b_1    : in boolean;
+-- >        result : out std_logic_vector(65 downto 0));
+-- > end;
 --
 -- However, we can change this by using 'PortName's. So by:
 --
@@ -317,13 +311,11 @@ instance Lift TopEntity where
 --
 -- we get:
 --
--- @
--- entity f is
---   port(a   : in signed(63 downto 0);
---        b   : in std_logic_vector(64 downto 0);
---        res : out std_logic_vector(65 downto 0));
--- end;
--- @
+-- > entity f is
+-- >   port(a   : in signed(63 downto 0);
+-- >        b   : in std_logic_vector(64 downto 0);
+-- >        res : out std_logic_vector(65 downto 0));
+-- > end;
 --
 -- If we want to name fields for tuples/records we have to use 'PortProduct'
 --
@@ -340,15 +332,13 @@ instance Lift TopEntity where
 --
 -- So that we get:
 --
--- @
--- entity f is
---   port(a     : in signed(63 downto 0);
---        b     : in signed(63 downto 0);
---        c     : in boolean;
---        res_q : out std_logic_vector(64 downto 0);
---        res_1 : out boolean);
--- end;
--- @
+-- > entity f is
+-- >   port(a     : in signed(63 downto 0);
+-- >        b     : in signed(63 downto 0);
+-- >        c     : in boolean;
+-- >        res_q : out std_logic_vector(64 downto 0);
+-- >        res_1 : out boolean);
+-- > end;
 --
 -- Notice how we didn't name the second field of the result, and the second
 -- output port got 'PortProduct' name, \"res\", as a prefix for its name.