Add Haddock `/Since: 4.5.[01].0/` comments to symbols
authorHerbert Valerio Riedel <hvr@gnu.org>
Sun, 22 Sep 2013 14:59:08 +0000 (16:59 +0200)
committerHerbert Valerio Riedel <hvr@gnu.org>
Sun, 22 Sep 2013 16:32:50 +0000 (18:32 +0200)
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 <hvr@gnu.org>
Data/Bits.hs
Data/List.hs
Data/Monoid.hs
Data/Typeable/Internal.hs
Debug/Trace.hs
GHC/Conc/Sync.lhs
GHC/IO/Encoding.hs
GHC/Stack.hsc
GHC/Stats.hsc
System/IO/Unsafe.hs
Text/Read/Lex.hs

index 9eb024c..2654a80 100644 (file)
@@ -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,
index 7998976..130ceb2 100644 (file)
@@ -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) []
 
index 1a17a32..a7059e6 100644 (file)
@@ -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 (<>) #-}
index 8917da9..447b069 100644 (file)
@@ -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
index a857760..0cb5fe4 100644 (file)
@@ -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 ->
index 3461c7c..5ba0fc4 100644 (file)
@@ -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
 
index 052955c..e3d7c3e 100644 (file)
@@ -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)
index 56b317a..b95594e 100644 (file)
@@ -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
index 5108dd3..07cab07 100644 (file)
@@ -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
index eb6eef6..99284f2 100644 (file)
@@ -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)
index f2ef4cc..ed049f8 100644 (file)
@@ -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))