Add Haddock `/Since: 4.6.0.0/` comments to symbols
authorHerbert Valerio Riedel <hvr@gnu.org>
Sat, 21 Sep 2013 16:04:19 +0000 (18:04 +0200)
committerHerbert Valerio Riedel <hvr@gnu.org>
Sat, 21 Sep 2013 16:07:25 +0000 (18:07 +0200)
This commit retroactively adds `/Since: 4.6.0.0/` annotations to symbols
newly added/exposed in `base-4.6.0.0` (as shipped with GHC 7.6.1).

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 <hvr@gnu.org>
16 files changed:
Control/Concurrent.hs
Control/Concurrent/MVar.hs
Data/Bits.hs
Data/IORef.hs
Data/Ord.hs
Data/STRef.hs
GHC/Conc/Sync.lhs
GHC/Exception.lhs
GHC/Generics.hs
GHC/IP.hs
GHC/Stats.hsc
GHC/TypeLits.hs
System/Environment.hs
System/Environment/ExecutablePath.hsc
Text/Read.hs
Text/Read/Lex.hs

index ce08166..5637db5 100644 (file)
@@ -196,6 +196,7 @@ attribute will block all other threads.
 -- This function is useful for informing the parent when a child
 -- terminates, for example.
 --
+-- /Since: 4.6.0.0/
 forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
 forkFinally action and_then =
   mask $ \restore ->
index c9ed3e1..5908729 100644 (file)
@@ -217,6 +217,8 @@ modifyMVar m io =
 {-|
   Like 'modifyMVar_', but the @IO@ action in the second argument is executed with
   asynchronous exceptions masked.
+
+  /Since: 4.6.0.0/
 -}
 {-# INLINE modifyMVarMasked_ #-}
 modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
@@ -229,6 +231,8 @@ modifyMVarMasked_ m io =
 {-|
   Like 'modifyMVar', but the @IO@ action in the second argument is executed with
   asynchronous exceptions masked.
+
+  /Since: 4.6.0.0/
 -}
 {-# INLINE modifyMVarMasked #-}
 modifyMVarMasked :: MVar a -> (a -> IO (a,b)) -> IO b
@@ -245,6 +249,8 @@ addMVarFinalizer = GHC.MVar.addMVarFinalizer
 
 -- | Make a 'Weak' pointer to an 'MVar', using the second argument as
 -- a finalizer to run when 'MVar' is garbage-collected
+--
+-- /Since: 4.6.0.0/
 mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
 mkWeakMVar m@(MVar m#) f = IO $ \s ->
   case mkWeak# m# m f s of (# s1, w #) -> (# s1, Weak w #)
index 08ff6f9..9eb024c 100644 (file)
@@ -269,6 +269,8 @@ class Bits b => FiniteBits b where
 -- | Default implementation for 'bit'.
 --
 -- Note that: @bitDefault i = 1 `shiftL` i@
+--
+-- /Since: 4.6.0.0/
 bitDefault :: (Bits a, Num a) => Int -> a
 bitDefault = \i -> 1 `shiftL` i
 {-# INLINE bitDefault #-}
@@ -276,6 +278,8 @@ bitDefault = \i -> 1 `shiftL` i
 -- | Default implementation for 'testBit'.
 --
 -- Note that: @testBitDefault x i = (x .&. bit i) /= 0@
+--
+-- /Since: 4.6.0.0/
 testBitDefault ::  (Bits a, Num a) => a -> Int -> Bool
 testBitDefault = \x i -> (x .&. bit i) /= 0
 {-# INLINE testBitDefault #-}
@@ -284,6 +288,8 @@ testBitDefault = \x i -> (x .&. bit i) /= 0
 --
 -- This implementation is intentionally naive. Instances are expected to provide
 -- an optimized implementation for their size.
+--
+-- /Since: 4.6.0.0/
 popCountDefault :: (Bits a, Num a) => a -> Int
 popCountDefault = go 0
  where
index f4eb9ec..1c1bb1b 100644 (file)
@@ -70,6 +70,8 @@ modifyIORef :: IORef a -> (a -> a) -> IO ()
 modifyIORef ref f = readIORef ref >>= writeIORef ref . f
 
 -- |Strict version of 'modifyIORef'
+--
+-- /Since: 4.6.0.0/
 modifyIORef' :: IORef a -> (a -> a) -> IO ()
 modifyIORef' ref f = do
     x <- readIORef ref
@@ -100,6 +102,8 @@ atomicModifyIORef = GHC.IORef.atomicModifyIORef
 
 -- | Strict version of 'atomicModifyIORef'.  This forces both the value stored
 -- in the 'IORef' as well as the value returned.
+--
+-- /Since: 4.6.0.0/
 atomicModifyIORef' :: IORef a -> (a -> (a,b)) -> IO b
 atomicModifyIORef' ref f = do
     b <- atomicModifyIORef ref
@@ -109,6 +113,8 @@ atomicModifyIORef' ref f = do
 
 -- | Variant of 'writeIORef' with the \"barrier to reordering\" property that
 -- 'atomicModifyIORef' has.
+--
+-- /Since: 4.6.0.0/
 atomicWriteIORef :: IORef a -> a -> IO ()
 atomicWriteIORef ref a = do
     x <- atomicModifyIORef ref (\_ -> (a, ()))
index 1748555..f7d32f6 100644 (file)
@@ -40,6 +40,8 @@ comparing p x y = compare (p x) (p y)
 -- values thus wrapped will give you the opposite of their normal sort order.
 -- This is particularly useful when sorting in generalised list comprehensions,
 -- as in: @then sortWith by 'Down' x@
+--
+-- /Since: 4.6.0.0/
 newtype Down a = Down a deriving (Eq)
 
 instance Ord a => Ord (Down a) where
index 486cc4b..dc65abc 100644 (file)
@@ -47,6 +47,8 @@ modifySTRef :: STRef s a -> (a -> a) -> ST s ()
 modifySTRef ref f = writeSTRef ref . f =<< readSTRef ref
 
 -- | Strict version of 'modifySTRef'
+--
+-- /Since: 4.6.0.0/
 modifySTRef' :: STRef s a -> (a -> a) -> ST s ()
 modifySTRef' ref f = do
     x <- readSTRef ref
index 3020b07..3461c7c 100644 (file)
@@ -507,6 +507,7 @@ threadCapability (ThreadId t) = IO $ \s ->
 -- caller must use @deRefWeak@ first to determine whether the thread
 -- still exists.
 --
+-- /Since: 4.6.0.0/
 mkWeakThreadId :: ThreadId -> IO (Weak ThreadId)
 mkWeakThreadId t@(ThreadId t#) = IO $ \s ->
    case mkWeakNoFinalizer# t# t s of
index 7d40a94..b878b6c 100644 (file)
@@ -191,7 +191,7 @@ data ArithException
   | LossOfPrecision
   | DivideByZero
   | Denormal
-  | RatioZeroDenominator
+  | RatioZeroDenominator -- ^ /Since: 4.6.0.0/
   deriving (Eq, Ord, Typeable)
 
 divZeroException, overflowException, ratioZeroDenomException  :: SomeException
index 6ab1e9e..8937f53 100644 (file)
@@ -23,7 +23,8 @@
 -- (<http://www.haskell.org/haskellwiki/GHC.Generics>)
 -- or use the generic-deriving package on Hackage:
 -- <http://hackage.haskell.org/package/generic-deriving>.
--- 
+--
+-- /Since: 4.6.0.0/
 -----------------------------------------------------------------------------
 
 module GHC.Generics  (
index 762f26b..4794c05 100644 (file)
--- a/GHC/IP.hs
+++ b/GHC/IP.hs
@@ -3,6 +3,8 @@
 {-# LANGUAGE KindSignatures #-}
 {-# LANGUAGE DataKinds #-}
 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
+
+-- | /Since: 4.6.0.0/
 module GHC.IP (IP(..)) where
 
 import GHC.TypeLits
index 024d1b2..5108dd3 100644 (file)
@@ -28,6 +28,10 @@ import Foreign.Ptr
 #include "Rts.h"
 
 foreign import ccall "getGCStats"        getGCStats_       :: Ptr () -> IO ()
+
+-- | Returns whether GC stats have been enabled (with @+RTS -T@, for example).
+--
+-- /Since: 4.6.0.0/
 foreign import ccall "getGCStatsEnabled" getGCStatsEnabled :: IO Bool
 
 -- I'm probably violating a bucket of constraints here... oops.
index 0f32ae6..3f95646 100644 (file)
 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
 {-| This module is an internal GHC module.  It declares the constants used
 in the implementation of type-level natural numbers.  The programmer interface
-for working with type-level naturals should be defined in a separate library. -}
+for working with type-level naturals should be defined in a separate library.
+
+/Since: 4.6.0.0/
+-}
 
 module GHC.TypeLits
   ( -- * Kinds
index 4288a60..34eea8c 100644 (file)
@@ -213,6 +213,8 @@ foreign import WINDOWS_CCONV unsafe "windows.h GetLastError"
 -- there is no such value.
 --
 -- For POSIX users, this is equivalent to 'System.Posix.Env.getEnv'.
+--
+-- /Since: 4.6.0.0/
 lookupEnv :: String -> IO (Maybe String)
 #ifdef mingw32_HOST_OS
 lookupEnv name = withCWString name $ \s -> try_size s 256
index 10ef158..4f863f2 100644 (file)
@@ -13,6 +13,7 @@
 --
 -- Function to retrieve the absolute filepath of the current executable.
 --
+-- /Since: 4.6.0.0/
 -----------------------------------------------------------------------------
 
 module System.Environment.ExecutablePath ( getExecutablePath ) where
@@ -52,6 +53,8 @@ import System.Posix.Internals
 --
 -- Note that for scripts and interactive sessions, this is the path to
 -- the interpreter (e.g. ghci.)
+--
+-- /Since: 4.6.0.0/
 getExecutablePath :: IO FilePath
 
 --------------------------------------------------------------------------------
index b2c3d6b..6c9d89d 100644 (file)
@@ -62,6 +62,8 @@ reads = readsPrec minPrec
 -- | Parse a string using the 'Read' instance.
 -- Succeeds if there is exactly one valid result.
 -- A 'Left' value indicates a parse error.
+--
+-- /Since: 4.6.0.0/
 readEither :: Read a => String -> Either String a
 readEither s =
   case [ x | (x,"") <- readPrec_to_S read' minPrec s ] of
@@ -76,6 +78,8 @@ readEither s =
 
 -- | Parse a string using the 'Read' instance.
 -- Succeeds if there is exactly one valid result.
+--
+-- /Since: 4.6.0.0/
 readMaybe :: Read a => String -> Maybe a
 readMaybe s = case readEither s of
                 Left _  -> Nothing
index 28bad33..f2ef4cc 100644 (file)
@@ -61,6 +61,7 @@ data Lexeme
   | EOF
  deriving (Eq, Show)
 
+-- | /Since: 4.6.0.0/
 data Number = MkNumber Int              -- Base
                        Digits           -- Integral part
             | MkDecimal Digits          -- Integral part
@@ -130,6 +131,7 @@ numberToRangedRational (neg, pos) n@(MkDecimal iPart mFPart (Just exp))
                 else Just (numberToRational n)
 numberToRangedRational _ n = Just (numberToRational n)
 
+-- | /Since: 4.6.0.0/
 numberToRational :: Number -> Rational
 numberToRational (MkNumber base iPart) = val (fromIntegral base) 0 iPart % 1
 numberToRational (MkDecimal iPart mFPart mExp)