Commit 0a5ecb53 authored by Herbert Valerio Riedel's avatar Herbert Valerio Riedel 🕺

Add Haddock `/Since: 4.5.[01].0/` comments to symbols

This commit retroactively adds `/Since: 4.5.[01].0/` annotations to symbols
newly added/exposed in `base-4.5.[01].0` (as shipped with GHC 7.4.[12]).

See also 6368362f which adds the respective annotation for symbols newly
added in `base-4.7.0.0` (that goes together with GHC 7.8.1).
Signed-off-by: Herbert Valerio Riedel's avatarHerbert Valerio Riedel <hvr@gnu.org>
parent 2642d9f6
......@@ -185,7 +185,9 @@ class Eq a => Bits a where
result is undefined for negative shift amounts and shift amounts
greater or equal to the 'bitSize'.
Defaults to 'shiftL' unless defined explicitly by an instance. -}
Defaults to 'shiftL' unless defined explicitly by an instance.
/Since: 4.5.0.0/ -}
unsafeShiftL :: a -> Int -> a
{-# INLINE unsafeShiftL #-}
x `unsafeShiftL` i = x `shiftL` i
......@@ -212,7 +214,9 @@ class Eq a => Bits a where
i.e. they fill the top bits with 1 if the @x@ is negative
and with 0 otherwise.
Defaults to 'shiftR' unless defined explicitly by an instance. -}
Defaults to 'shiftR' unless defined explicitly by an instance.
/Since: 4.5.0.0/ -}
unsafeShiftR :: a -> Int -> a
{-# INLINE unsafeShiftR #-}
x `unsafeShiftR` i = x `shiftR` i
......@@ -238,7 +242,9 @@ class Eq a => Bits a where
x `rotateR` i = x `rotate` (-i)
{-| Return the number of set bits in the argument. This number is
known as the population count or the Hamming weight. -}
known as the population count or the Hamming weight.
/Since: 4.5.0.0/ -}
popCount :: a -> Int
{-# MINIMAL (.&.), (.|.), xor, complement,
......
......@@ -224,7 +224,8 @@ infix 5 \\ -- comment to fool cpp
-- > dropWhileEnd isSpace "foo\n" == "foo"
-- > dropWhileEnd isSpace "foo bar" == "foo bar"
-- > dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined
--
-- /Since: 4.5.0.0/
dropWhileEnd :: (a -> Bool) -> [a] -> [a]
dropWhileEnd p = foldr (\x xs -> if p x && null xs then [] else x : xs) []
......
......@@ -88,6 +88,8 @@ class Monoid a where
infixr 6 <>
-- | An infix synonym for 'mappend'.
--
-- /Since: 4.5.0.0/
(<>) :: Monoid m => m -> m -> m
(<>) = mappend
{-# INLINE (<>) #-}
......
......@@ -84,9 +84,9 @@ instance Ord TypeRep where
-- be built using 'mkTyCon'.
data TyCon = TyCon {
tyConHash :: {-# UNPACK #-} !Fingerprint,
tyConPackage :: String,
tyConModule :: String,
tyConName :: String
tyConPackage :: String, -- ^ /Since: 4.5.0.0/
tyConModule :: String, -- ^ /Since: 4.5.0.0/
tyConName :: String -- ^ /Since: 4.5.0.0/
}
instance Eq TyCon where
......
......@@ -67,6 +67,7 @@ import GHC.Stack
-- | The 'traceIO' function outputs the trace message from the IO monad.
-- This sequences the output with respect to other IO actions.
--
-- /Since: 4.5.0.0/
traceIO :: String -> IO ()
traceIO msg = do
withCString "%s\n" $ \cfmt ->
......@@ -174,6 +175,7 @@ traceShowM = traceM . show
-- stack correspond to @SCC@ annotations, so it is a good idea to use
-- @-fprof-auto@ or @-fprof-auto-calls@ to add SCC annotations automatically.
--
-- /Since: 4.5.0.0/
traceStack :: String -> a -> a
traceStack str expr = unsafePerformIO $ do
traceIO str
......@@ -206,6 +208,7 @@ traceStack str expr = unsafePerformIO $ do
-- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
-- that uses 'traceEvent'.
--
-- /Since: 4.5.0.0/
traceEvent :: String -> a -> a
traceEvent msg expr = unsafeDupablePerformIO $ do
traceEventIO msg
......@@ -217,6 +220,7 @@ traceEvent msg expr = unsafeDupablePerformIO $ do
-- Compared to 'traceEvent', 'traceEventIO' sequences the event with respect to
-- other IO actions.
--
-- /Since: 4.5.0.0/
traceEventIO :: String -> IO ()
traceEventIO msg =
GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
......
......@@ -283,6 +283,8 @@ garbage collection. It is strongly recommended that the number of
capabilities is not set larger than the number of physical processor
cores, and it may often be beneficial to leave one or more cores free
to avoid contention with other processes in the machine.
/Since: 4.5.0.0/
-}
setNumCapabilities :: Int -> IO ()
setNumCapabilities i = c_setNumCapabilities (fromIntegral i)
......@@ -290,6 +292,9 @@ setNumCapabilities i = c_setNumCapabilities (fromIntegral i)
foreign import ccall safe "setNumCapabilities"
c_setNumCapabilities :: CUInt -> IO ()
-- | Returns the number of CPUs that the machine has
--
-- /Since: 4.5.0.0/
getNumProcessors :: IO Int
getNumProcessors = fmap fromIntegral c_getNumberOfProcessors
......
......@@ -103,6 +103,8 @@ utf32be :: TextEncoding
utf32be = UTF32.utf32be
-- | The Unicode encoding of the current locale
--
-- /Since: 4.5.0.0/
getLocaleEncoding :: IO TextEncoding
-- | The Unicode encoding of the current locale, but allowing arbitrary
......@@ -114,14 +116,20 @@ getLocaleEncoding :: IO TextEncoding
-- On Windows, this encoding *should not* be used if possible because
-- the use of code pages is deprecated: Strings should be retrieved
-- via the "wide" W-family of UTF-16 APIs instead
--
-- /Since: 4.5.0.0/
getFileSystemEncoding :: IO TextEncoding
-- | The Unicode encoding of the current locale, but where undecodable
-- bytes are replaced with their closest visual match. Used for
-- the 'CString' marshalling functions in "Foreign.C.String"
--
-- /Since: 4.5.0.0/
getForeignEncoding :: IO TextEncoding
-- | /Since: 4.5.0.0/
setLocaleEncoding, setFileSystemEncoding, setForeignEncoding :: TextEncoding -> IO ()
(getLocaleEncoding, setLocaleEncoding) = mkGlobal initLocaleEncoding
(getFileSystemEncoding, setFileSystemEncoding) = mkGlobal initFileSystemEncoding
(getForeignEncoding, setForeignEncoding) = mkGlobal initForeignEncoding
......@@ -131,6 +139,7 @@ mkGlobal x = unsafePerformIO $ do
x_ref <- newIORef x
return (readIORef x_ref, writeIORef x_ref)
-- | /Since: 4.5.0.0/
initLocaleEncoding, initFileSystemEncoding, initForeignEncoding :: TextEncoding
#if !defined(mingw32_HOST_OS)
......
......@@ -10,6 +10,7 @@
--
-- Access to GHC's call-stack simulation
--
-- /Since: 4.5.0.0/
-----------------------------------------------------------------------------
{-# LANGUAGE UnboxedTuples, MagicHash, EmptyDataDecls #-}
......@@ -82,6 +83,8 @@ ccSrcSpan p = (# peek CostCentre, srcloc) p
-- and contains suitable SCC annotations (e.g. by using @-fprof-auto@).
-- Otherwise, the list returned is likely to be empty or
-- uninformative.
--
-- /Since: 4.5.0.0/
currentCallStack :: IO [String]
currentCallStack = ccsToStrings =<< getCurrentCCS ()
......@@ -101,6 +104,9 @@ ccsToStrings ccs0 = go ccs0 []
then return acc
else go parent ((mdl ++ '.':lbl ++ ' ':'(':loc ++ ")") : acc)
-- | Get the stack trace attached to an object.
--
-- /Since: 4.5.0.0/
whoCreated :: a -> IO [String]
whoCreated obj = do
ccs <- getCCSOf obj
......
......@@ -11,6 +11,7 @@
--
-- This module is GHC-only and should not be considered portable.
--
-- /Since: 4.5.0.0/
-----------------------------------------------------------------------------
module GHC.Stats
( GCStats(..)
......@@ -37,6 +38,8 @@ foreign import ccall "getGCStatsEnabled" getGCStatsEnabled :: IO Bool
-- I'm probably violating a bucket of constraints here... oops.
-- | Global garbage collection and memory statistics.
--
-- /Since: 4.5.0.0/
data GCStats = GCStats
{ bytesAllocated :: !Int64 -- ^ Total number of bytes allocated
, numGcs :: !Int64 -- ^ Number of garbage collections performed
......@@ -83,6 +86,8 @@ data GCStats = GCStats
-- | Retrieves garbage collection and memory statistics as of the last
-- garbage collection. If you would like your statistics as recent as
-- possible, first run a 'System.Mem.performGC'.
--
-- /Since: 4.5.0.0/
getGCStats :: IO GCStats
getGCStats = do
statsEnabled <- getGCStatsEnabled
......
......@@ -40,6 +40,7 @@ import Control.Exception
-- In this case, the child thread will receive a @NonTermination@
-- exception instead of waiting for the value of @r@ to be computed.
--
-- /Since: 4.5.0.0/
unsafeFixIO :: (a -> IO a) -> IO a
unsafeFixIO k = do
ref <- newIORef (throw NonTermination)
......
......@@ -57,7 +57,7 @@ data Lexeme
| Punc String -- ^ Punctuation or reserved symbol, e.g. @(@, @::@
| Ident String -- ^ Haskell identifier, e.g. @foo@, @Baz@
| Symbol String -- ^ Haskell symbol, e.g. @>>@, @:%@
| Number Number
| Number Number -- ^ /Since: 4.6.0.0/
| EOF
deriving (Eq, Show)
......@@ -69,6 +69,7 @@ data Number = MkNumber Int -- Base
(Maybe Integer) -- Exponent
deriving (Eq, Show)
-- | /Since: 4.5.1.0/
numberToInteger :: Number -> Maybe Integer
numberToInteger (MkNumber base iPart) = Just (val (fromIntegral base) 0 iPart)
numberToInteger (MkDecimal iPart Nothing Nothing) = Just (val 10 0 iPart)
......@@ -102,6 +103,7 @@ numberToFixed _ _ = Nothing
-- * We only worry about numbers that have an exponent. If they don't
-- have an exponent then the Rational won't be much larger than the
-- Number, so there is no problem
-- | /Since: 4.5.1.0/
numberToRangedRational :: (Int, Int) -> Number
-> Maybe Rational -- Nothing = Inf
numberToRangedRational (neg, pos) n@(MkDecimal iPart mFPart (Just exp))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment