From 386c6395534c580cbb3568ee4bacd4d375e87b0c Mon Sep 17 00:00:00 2001 From: Peter Lebbing Date: Fri, 8 Dec 2023 16:48:35 +0100 Subject: [PATCH] Haddock: Fix very confusing formatting errors 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. --- clash-prelude/src/Clash/Explicit/Testbench.hs | 4 ++-- clash-prelude/src/Clash/Signal/Bundle.hs | 4 ++-- clash-prelude/src/Clash/Sized/RTree.hs | 1 + clash-prelude/src/Clash/Tutorial.hs | 8 ++++---- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/clash-prelude/src/Clash/Explicit/Testbench.hs b/clash-prelude/src/Clash/Explicit/Testbench.hs index d39e139954..86c83c051c 100644 --- a/clash-prelude/src/Clash/Explicit/Testbench.hs +++ b/clash-prelude/src/Clash/Explicit/Testbench.hs @@ -449,8 +449,8 @@ tbEnableGen = toEnable (pure True) -- where -- testInput = pure ((1 :> 2 :> 3 :> Nil) :> (4 :> 5 :> 6 :> Nil) :> Nil) -- expectedOutput = outputVerifier' ((1:>2:>3:>4:>5:>6:>Nil):>Nil) --- done = exposeClockResetEnable (expectedOutput (topEntity <$> testInput)) clk rst --- clk = 'tbSystemClockGen' (not <\$\> done) +-- done = exposeClockResetEnable (expectedOutput (topEntity \<\$> testInput)) clk rst +-- clk = 'tbSystemClockGen' (not \<\$> done) -- rst = systemResetGen -- @ tbSystemClockGen diff --git a/clash-prelude/src/Clash/Signal/Bundle.hs b/clash-prelude/src/Clash/Signal/Bundle.hs index 79bc7a03ef..51dbe9f2a8 100644 --- a/clash-prelude/src/Clash/Signal/Bundle.hs +++ b/clash-prelude/src/Clash/Signal/Bundle.hs @@ -82,10 +82,10 @@ import Clash.Sized.RTree (RTree, lazyT) -- type Unbundled dom (Pair a b) = Pair (Signal dom a) (Signal dom b) -- -- -- bundle :: Pair (Signal dom a) (Signal dom b) -> Signal dom (Pair a b) --- bundle (MkPair as bs) = MkPair <$> as <*> bs +-- bundle (MkPair as bs) = MkPair '<$>' as '<*>' bs -- -- -- unbundle :: Signal dom (Pair a b) -> Pair (Signal dom a) (Signal dom b) --- unbundle pairs = MkPair (getA <$> pairs) (getB <$> pairs) +-- unbundle pairs = MkPair (getA '<$>' pairs) (getB '<$>' pairs) -- @ class Bundle a where diff --git a/clash-prelude/src/Clash/Sized/RTree.hs b/clash-prelude/src/Clash/Sized/RTree.hs index 47dd2d4312..bf698cb962 100644 --- a/clash-prelude/src/Clash/Sized/RTree.hs +++ b/clash-prelude/src/Clash/Sized/RTree.hs @@ -298,6 +298,7 @@ We have such an adder in the form of the 'Clash.Class.Num.add' function, as defined in the instance 'Clash.Class.Num.ExtendingNum' instance of 'Index'. However, we cannot simply use 'Clash.Sized.Vector.fold' to create a tree-structure of 'Clash.Class.Num.add's: + #if __GLASGOW_HASKELL__ >= 900 >>> :{ let populationCount' :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1)) diff --git a/clash-prelude/src/Clash/Tutorial.hs b/clash-prelude/src/Clash/Tutorial.hs index fe19b316cf..9827ef85b9 100644 --- a/clash-prelude/src/Clash/Tutorial.hs +++ b/clash-prelude/src/Clash/Tutorial.hs @@ -1187,9 +1187,9 @@ BlackBox: begin if ~IF~ACTIVEEDGE[Rising][0]~THENrising_edge~ELSEfalling_edge~FI(~ARG[3]) then if ~ARG[7] ~IF ~ISACTIVEENABLE[4] ~THEN and ~ARG[4] ~ELSE ~FI then - ~SYM[2](~SYM[5]) <= ~TOBV[~ARG[9]][~TYP[9]]; + ~SYM\[2](~SYM[5]) <= ~TOBV[~ARG[9]][~TYP[9]]; end if; - ~RESULT <= fromSLV(~SYM[2](~SYM[4])) + ~RESULT <= fromSLV(~SYM\[2](~SYM[4])) -- pragma translate_off after 1 ps -- pragma translate_on @@ -1200,9 +1200,9 @@ BlackBox: begin if ~IF~ACTIVEEDGE[Rising][0]~THENrising_edge~ELSEfalling_edge~FI(~ARG[3]) then if ~ARG[7] ~IF ~ISACTIVEENABLE[4] ~THEN and ~ARG[4] ~ELSE ~FI then - ~SYM[2](~SYM[5]) <= ~ARG[9]; + ~SYM\[2](~SYM[5]) <= ~ARG[9]; end if; - ~RESULT <= ~SYM[2](~SYM[4]) + ~RESULT <= ~SYM\[2](~SYM[4]) -- pragma translate_off after 1 ps -- pragma translate_on