Various small fixes - part 11 (#2152)

Various small fixes

Improve `Show BlackBox`. Add parentheses for proper precedence for
`BBTemplate`. It showed in `show (BlackBoxE ... (BBTemplate ...) ...)`,
where the parentheses were missing, making it a surprising read.

Co-authored-by: Leon Schoorl <[email protected]>

Author: DigitalBrains1

README.md

@@ -62,7 +62,7 @@ git checkout 1.2
 
 Note that release branches might contain non-released patches.
 
-## GHC compatability
+## GHC compatibility
 |      | Linux | Windows | macOS |
 |------|-------|---------|-------|
 | 8.6  | ✔️     | ✔️      | ✔️     |

clash-lib/src/Clash/Driver/Types.hs

@@ -338,7 +338,7 @@ data ClashOpts = ClashOpts
   , opt_color :: OverridingBool
   -- ^ Show colors in debug output
   --
-  -- Command line flag: -fclash-no-prim-warn
+  -- Command line flag: -fdiagnostics-color
   , opt_intWidth :: Int
   -- ^ Set the bit width for the Int/Word/Integer types. The only allowed values
   -- are 32 or 64.

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

@@ -2,7 +2,7 @@
   Copyright  :  (C) 2012-2016, University of Twente,
                     2017     , Myrtle Software Ltd,
                     2017-2018, Google Inc.
-                    2020-2021, QBayLogic B.V.
+                    2020-2022, QBayLogic B.V.
   License    :  BSD2 (see the file LICENSE)
   Maintainer :  QBayLogic B.V. <[email protected]>
 
@@ -740,9 +740,11 @@ data TemplateFunction where
     -> TemplateFunction
 
 instance Show BlackBox where
-  show (BBTemplate t)  = "BBTemplate " <> show t
-  show (BBFunction nm hsh _) =
-    "<TemplateFunction(nm=" ++ show nm ++ ", hash=" ++ show hsh ++ ")>"
+  showsPrec d (BBTemplate t) =
+    showParen (d > 10) $ ("BBTemplate " ++) . showsPrec 11 t
+  showsPrec _ (BBFunction nm hsh _) =
+    ("<TemplateFunction(nm=" ++) . shows nm . (", hash=" ++) . shows hsh .
+    (")>" ++)
 
 instance NFData TemplateFunction where
   rnf (TemplateFunction is f _) = rnf is `seq` f `seq` ()

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

@@ -25,7 +25,7 @@ module Clash.Primitives.DSL
     BlackBoxHaskellOpts(..)
   , blackBoxHaskell
 
-  -- * declarations
+  -- * Declarations
   , BlockState (..)
   , TExpr
   , declaration
@@ -139,10 +139,10 @@ instance Default BlackBoxHaskellOpts where
 -- | Create a blackBoxHaskell primitive. To be used as part of an annotation:
 --
 -- @
--- {-# ANN myFunction (blackBoxHaskell 'myFunction 'myBBF def{_ignoredArguments=[2,3]}) #-}
+-- {-\# ANN myFunction (blackBoxHaskell 'myFunction 'myBBF def{_ignoredArguments=[1,2]}) \#-}
 -- @
 --
--- [2,3] would mean this blackbox __ignores__ its second and third argument.
+-- @[1,2]@ would mean this blackbox __ignores__ its second and third argument.
 blackBoxHaskell
   :: Name
   -- ^ blackbox name

clash-prelude/src/Clash/Class/AutoReg/Internal.hs

@@ -1,6 +1,6 @@
 {-|
   Copyright   :  (C) 2019     , Google Inc.,
-                     2021     , QBayLogic B.V.
+                     2021-2022, QBayLogic B.V.,
                      2021-2022, Myrtle.ai
   License     :  BSD2 (see the file LICENSE)
   Maintainer :  QBayLogic B.V. <[email protected]>
@@ -107,7 +107,7 @@ import           Control.Lens.Internal.TH     (bndrName)
 class NFDataX a => AutoReg a where
   -- | For documentation see class 'AutoReg'.
   --
-  -- This is version with explicit clock/reset/enable,
+  -- This is the version with explicit clock\/reset\/enable inputs,
   -- "Clash.Prelude" exports an implicit version of this: 'Clash.Prelude.autoReg'
   autoReg
     :: (HasCallStack, KnownDomain dom)

clash-prelude/src/Clash/Explicit/BlockRam.hs

@@ -416,6 +416,8 @@ module Clash.Explicit.BlockRam
   , RamOp(..)
     -- * Internal
   , blockRam#
+  , blockRamU#
+  , blockRam1#
   , trueDualPortBlockRam#
   )
 where

clash-prelude/src/Clash/Explicit/Mealy.hs

@@ -80,8 +80,8 @@ let macT s (x,y) = (s',s)
 --   -> 'Signal' dom Int
 -- dualMac clk rst en (a,b) (x,y) = s1 + s2
 --   where
---     s1 = 'mealy' clk rst en mac 0 ('bundle' (a,x))
---     s2 = 'mealy' clk rst en mac 0 ('bundle' (b,y))
+--     s1 = 'mealy' clk rst en macT 0 ('bundle' (a,x))
+--     s2 = 'mealy' clk rst en macT 0 ('bundle' (b,y))
 -- @
 mealy
   :: ( KnownDomain dom

clash-prelude/src/Clash/Explicit/Moore.hs

@@ -72,8 +72,8 @@ import           Clash.XException                 (NFDataX)
 --   -> 'Signal' dom Int
 -- dualMac clk rst en (a,b) (x,y) = s1 + s2
 --   where
---     s1 = 'moore' clk rst en mac id 0 ('bundle' (a,x))
---     s2 = 'moore' clk rst en mac id 0 ('bundle' (b,y))
+--     s1 = 'moore' clk rst en macT id 0 ('bundle' (a,x))
+--     s2 = 'moore' clk rst en macT id 0 ('bundle' (b,y))
 -- @
 moore
   :: ( KnownDomain dom

clash-prelude/src/Clash/Num/Overflowing.hs

@@ -1,10 +1,18 @@
+{-|
+Copyright  :  (C) 2021-2022, QBayLogic B.V.
+License    :  BSD2 (see the file LICENSE)
+Maintainer :  QBayLogic B.V. <[email protected]>
+-}
+
 {-# LANGUAGE DeriveAnyClass #-}
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE TypeFamilies #-}
 {-# LANGUAGE UndecidableInstances #-}
 
 module Clash.Num.Overflowing
-  ( Overflowing(fromOverflowing, hasOverflowed)
+  ( Overflowing
+  , fromOverflowing
+  , hasOverflowed
   , toOverflowing
   , clearOverflow
   ) where
@@ -31,7 +39,9 @@ import Clash.XException (NFDataX, ShowX)
 --
 data Overflowing a = Overflowing
   { fromOverflowing :: a
+    -- ^ Retrieve the value
   , hasOverflowed :: Bool
+    -- ^ 'True' when a computation has overflowed
   }
   deriving stock (Generic, Show)
   deriving anyclass (Binary, Hashable, NFData, NFDataX, ShowX)

clash-prelude/src/Clash/Prelude/Mealy.hs

@@ -71,8 +71,8 @@ let macT s (x,y) = (s',s)
 --   -> 'Signal' dom Int
 -- dualMac (a,b) (x,y) = s1 + s2
 --   where
---     s1 = 'mealy' mac 0 ('Clash.Signal.bundle' (a,x))
---     s2 = 'mealy' mac 0 ('Clash.Signal.bundle' (b,y))
+--     s1 = 'mealy' macT 0 ('Clash.Signal.bundle' (a,x))
+--     s2 = 'mealy' macT 0 ('Clash.Signal.bundle' (b,y))
 -- @
 mealy
   :: ( HiddenClockResetEnable dom