Add Haddock `/Since: 4.7.0.0/` comments to new symbols
authorHerbert Valerio Riedel <hvr@gnu.org>
Sat, 21 Sep 2013 12:16:45 +0000 (14:16 +0200)
committerHerbert Valerio Riedel <hvr@gnu.org>
Sat, 21 Sep 2013 12:16:45 +0000 (14:16 +0200)
These annotations were added in such a way, that the line

{{{
/Since: 4.7.0.0/
}}}

represents the last paragraph of the Haddock comment.

Maybe Haddock will have support for this meta-syntax at some point, and
be able to inherited the since-version property to the children of an
annotated symbol and display the since-version property in the rendered
documentation only in cases when it's not visually obvious (for
instance, when re-exporting documentation strings).

Signed-off-by: Herbert Valerio Riedel <hvr@gnu.org>
25 files changed:
Control/Concurrent.hs
Data/Bits.hs
Data/Bool.hs
Data/Either.hs
Data/Functor.hs
Data/OldTypeable.hs
Data/OldTypeable/Internal.hs
Data/Proxy.hs
Data/Type/Equality.hs
Data/Typeable/Internal.hs
Debug/Trace.hs
Foreign/C/Error.hs
GHC/Exts.hs
GHC/Fingerprint.hs
GHC/IO/Exception.hs
GHC/MVar.hs
GHC/Profiling.hs
GHC/Stack.hsc
GHC/TypeLits.hs
GHC/Word.hs
Numeric.hs
System/Environment.hs
System/Mem/StableName.hs
Text/Printf.hs
Text/Read/Lex.hs

index 25671bf..ce08166 100644 (file)
@@ -434,6 +434,8 @@ threadWaitWrite fd
 -- to read from a file descriptor. The second returned value
 -- is an IO action that can be used to deregister interest
 -- in the file descriptor.
+--
+-- /Since: 4.7.0.0/
 threadWaitReadSTM :: Fd -> IO (STM (), IO ())
 threadWaitReadSTM fd
 #ifdef mingw32_HOST_OS
@@ -456,6 +458,8 @@ threadWaitReadSTM fd
 -- can be written to a file descriptor. The second returned value
 -- is an IO action that can be used to deregister interest
 -- in the file descriptor.
+--
+-- /Since: 4.7.0.0/
 threadWaitWriteSTM :: Fd -> IO (STM (), IO ())
 threadWaitWriteSTM fd
 #ifdef mingw32_HOST_OS
index d32d45d..08ff6f9 100644 (file)
@@ -149,6 +149,8 @@ class Eq a => Bits a where
     {-| Return the number of bits in the type of the argument.  The actual
         value of the argument is ignored.  Returns Nothing
         for types that do not have a fixed bitsize, like 'Integer'.
+
+        /Since: 4.7.0.0/
         -}
     bitSizeMaybe      :: a -> Maybe Int
 
index 0dd8198..deeac80 100644 (file)
@@ -31,6 +31,8 @@ import GHC.Base
 -- | Case analysis for the 'Bool' type.
 -- @bool a b p@ evaluates to @a@ when @p@ is @False@, and evaluates to @b@
 -- when @p@ is @True@.
+--
+-- /Since: 4.7.0.0/
 bool :: a -> a -> Bool -> a
 bool f _ False = f
 bool _ t True  = t
index 5ed041d..b494e26 100644 (file)
@@ -90,11 +90,15 @@ partitionEithers = foldr (either left right) ([],[])
   right a ~(l, r) = (l, a:r)
 
 -- | Return `True` if the given value is a `Left`-value, `False` otherwise.
+--
+-- /Since: 4.7.0.0/
 isLeft :: Either a b -> Bool
 isLeft (Left  _) = True
 isLeft (Right _) = False
 
 -- | Return `True` if the given value is a `Right`-value, `False` otherwise.
+--
+-- /Since: 4.7.0.0/
 isRight :: Either a b -> Bool
 isRight (Left  _) = False
 isRight (Right _) = True
index a578bdd..fdf7c4b 100644 (file)
@@ -33,6 +33,9 @@ infixl 4 <$>
 
 infixl 4 $>
 
+-- | Flipped version of '$>'.
+--
+-- /Since: 4.7.0.0/
 ($>) :: Functor f => f a -> b -> f b
 ($>) = flip (<$)
 
index ab936c4..b0f4afc 100644 (file)
@@ -28,6 +28,7 @@
 -- deprecated; users are recommended to use the kind-polymorphic
 -- "Data.Typeable" module instead.
 --
+-- /Since: 4.7.0.0/
 -----------------------------------------------------------------------------
 
 module Data.OldTypeable {-# DEPRECATED "Use Data.Typeable instead" #-} -- deprecated in 7.8
index 9718237..2b02930 100644 (file)
@@ -10,6 +10,7 @@
 -- function mkTyCon which is used by derived instances of Typeable to
 -- construct a TyCon.
 --
+-- /Since: 4.7.0.0/
 -----------------------------------------------------------------------------
 
 {-# LANGUAGE CPP
index 083db91..4c2c5df 100644 (file)
@@ -12,6 +12,7 @@
 --
 -- Definition of a Proxy type (poly-kinded in GHC)
 --
+-- /Since: 4.7.0.0/
 -----------------------------------------------------------------------------
 
 module Data.Proxy
index 62b0241..5293ce6 100644 (file)
@@ -19,6 +19,7 @@
 -- Definition of propositional equality @(:=:)@. Pattern-matching on a variable
 -- of type @(a :=: b)@ produces a proof that @a ~ b@.
 --
+-- /Since: 4.7.0.0/
 -----------------------------------------------------------------------------
 
 
@@ -37,6 +38,8 @@ infix 4 :=:
 -- value, then the type @a@ is the same as the type @b@. To use this equality
 -- in practice, pattern-match on the @a :=: b@ to get out the @Refl@ constructor;
 -- in the body of the pattern-match, the compiler knows that @a ~ b@.
+--
+-- /Since: 4.7.0.0/
 data a :=: b where
   Refl :: a :=: a
 
index 5dd1417..8917da9 100644 (file)
@@ -193,6 +193,8 @@ class Typeable a where
   typeRep :: proxy a -> TypeRep
   -- ^ Takes a value of type @a@ and returns a concrete representation
   -- of that type.
+  --
+  -- /Version: 4.7.0.0/
 
 -- Keeping backwards-compatibility
 typeOf :: forall a. Typeable a => a -> TypeRep
index 7f78a85..a857760 100644 (file)
@@ -105,6 +105,8 @@ trace string expr = unsafePerformIO $ do
 
 {-|
 Like 'trace' but returns the message instead of a third value.
+
+/Since: 4.7.0.0/
 -}
 traceId :: String -> String
 traceId a = trace a a
@@ -127,6 +129,8 @@ traceShow = trace . show
 
 {-|
 Like 'traceShow' but returns the shown value instead of a third value.
+
+/Since: 4.7.0.0/
 -}
 traceShowId :: (Show a) => a -> a
 traceShowId a = trace (show a) a
@@ -141,6 +145,8 @@ monad, as 'traceIO' is in the 'IO' monad.
 >   traceM $ "x: " ++ show x
 >   y <- ...
 >   traceM $ "y: " ++ show y
+
+/Since: 4.7.0.0/
 -}
 traceM :: (Monad m) => String -> m ()
 traceM string = trace string $ return ()
@@ -153,6 +159,8 @@ Like 'traceM', but uses 'show' on the argument to convert it to a 'String'.
 >   traceMShow $ x
 >   y <- ...
 >   traceMShow $ x + y
+
+/Since: 4.7.0.0/
 -}
 traceShowM :: (Show a, Monad m) => a -> m ()
 traceShowM = traceM . show
@@ -246,6 +254,7 @@ traceEventIO msg =
 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
 -- that uses 'traceMarker'.
 --
+-- /Since: 4.7.0.0/
 traceMarker :: String -> a -> a
 traceMarker msg expr = unsafeDupablePerformIO $ do
     traceMarkerIO msg
@@ -257,6 +266,7 @@ traceMarker msg expr = unsafeDupablePerformIO $ do
 -- Compared to 'traceMarker', 'traceMarkerIO' sequences the event with respect to
 -- other IO actions.
 --
+-- /Since: 4.7.0.0/
 traceMarkerIO :: String -> IO ()
 traceMarkerIO msg =
   GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
index ad15edb..86a2df5 100644 (file)
@@ -204,6 +204,7 @@ eNOTDIR         = Errno (CONST_ENOTDIR)
 eNOTEMPTY       = Errno (CONST_ENOTEMPTY)
 eNOTSOCK        = Errno (CONST_ENOTSOCK)
 eNOTSUP         = Errno (CONST_ENOTSUP)
+-- ^ /Since: 4.7.0.0/
 eNOTTY          = Errno (CONST_ENOTTY)
 eNXIO           = Errno (CONST_ENXIO)
 eOPNOTSUPP      = Errno (CONST_EOPNOTSUPP)
index eee2509..1cea3fb 100755 (executable)
@@ -142,6 +142,8 @@ data SpecConstrAnnotation = NoSpecConstr | ForceSpecConstr
 
 -- | The 'IsList' class and its methods are intended to be used in
 --   conjunction with the OverloadedLists extension.
+--
+-- /Since: 4.7.0.0/
 class IsList l where
   -- | The 'Item' type function returns the type of items of the structure
   --   @l@.
index e8ab088..1f712f5 100644 (file)
@@ -73,6 +73,8 @@ fingerprintString str = unsafeDupablePerformIO $
 
 -- | Computes the hash of a given file.
 -- This function loops over the handle, running in constant memory.
+--
+-- /Since: 4.7.0.0/
 getFileHash :: FilePath -> IO Fingerprint
 getFileHash path = withBinaryFile path ReadMode $ \h -> do
   allocaBytes SIZEOF_STRUCT_MD5CONTEXT $ \pctxt -> do
index 6f37459..8691477 100644 (file)
@@ -110,6 +110,9 @@ instance Show AssertionFailed where
 
 -----
 
+-- |Superclass for asynchronous exceptions.
+--
+-- /Since: 4.7.0.0/
 data SomeAsyncException = forall e . Exception e => SomeAsyncException e
   deriving Typeable
 
@@ -118,9 +121,11 @@ instance Show SomeAsyncException where
 
 instance Exception SomeAsyncException
 
+-- |/Since: 4.7.0.0/
 asyncExceptionToException :: Exception e => e -> SomeException
 asyncExceptionToException = toException . SomeAsyncException
 
+-- |/Since: 4.7.0.0/
 asyncExceptionFromException :: Exception e => SomeException -> Maybe e
 asyncExceptionFromException x = do
     SomeAsyncException a <- fromException x
index 314a440..03facad 100644 (file)
@@ -156,6 +156,8 @@ tryPutMVar (MVar mvar#) x = IO $ \ s# ->
 -- |A non-blocking version of 'readMVar'.  The 'tryReadMVar' function
 -- returns immediately, with 'Nothing' if the 'MVar' was empty, or
 -- @'Just' a@ if the 'MVar' was full with contents @a@.
+--
+-- /Since: 4.7.0.0/
 tryReadMVar :: MVar a -> IO (Maybe a)
 tryReadMVar (MVar m) = IO $ \ s ->
     case tryReadMVar# m s of
index 10a3d5b..2654ef7 100644 (file)
@@ -1,5 +1,6 @@
 {-# LANGUAGE ForeignFunctionInterface #-}
 
+-- | /Since: 4.7.0.0/
 module GHC.Profiling where
 
 foreign import ccall startProfTimer :: IO ()
index 849a48c..56b317a 100644 (file)
@@ -111,6 +111,8 @@ renderStack strs = "Stack trace:" ++ concatMap ("\n  "++) (reverse strs)
 
 -- | Like the function 'error', but appends a stack trace to the error
 -- message if one is available.
+--
+-- /Since: 4.7.0.0/
 errorWithStackTrace :: String -> a
 errorWithStackTrace x = unsafeDupablePerformIO $ do
    stack <- ccsToStrings =<< getCurrentCCS x
index f71f654..0f32ae6 100644 (file)
@@ -316,6 +316,8 @@ type instance FromNat1 (Succ n) = 1 + FromNat1 n
 --------------------------------------------------------------------------------
 
 -- | A type that provides evidence for equality between two types.
+--
+-- /Since: 4.7.0.0/
 data (:~:) :: k -> k -> * where
   Refl :: a :~: a
 
index 1581c4a..d2568ea 100644 (file)
@@ -303,6 +303,9 @@ instance Bits Word16 where
 instance FiniteBits Word16 where
     finiteBitSize _ = 16
 
+-- | Swap bytes in 'Word16'.
+--
+-- /Since: 4.7.0.0/
 byteSwap16 :: Word16 -> Word16
 byteSwap16 (W16# w#) = W16# (narrow16Word# (byteSwap16# w#))
 
@@ -530,6 +533,9 @@ instance Read Word32 where
     readsPrec p s = [(fromIntegral (x::Int), r) | (x, r) <- readsPrec p s]
 #endif
 
+-- | Reverse order of bytes in 'Word32'.
+--
+-- /Since: 4.7.0.0/
 byteSwap32 :: Word32 -> Word32
 byteSwap32 (W32# w#) = W32# (narrow32Word# (byteSwap32# w#))
 
@@ -781,6 +787,9 @@ instance Ix Word64 where
 instance Read Word64 where
     readsPrec p s = [(fromInteger x, r) | (x, r) <- readsPrec p s]
 
+-- | Reverse order of bytes in 'Word64'.
+--
+-- /Since: 4.7.0.0/
 #if WORD_SIZE_IN_BITS < 64
 byteSwap64 :: Word64 -> Word64
 byteSwap64 (W64# w#) = W64# (byteSwap64# w#)
index 88b2e1a..4a1a5b1 100644 (file)
@@ -187,6 +187,8 @@ showGFloat d x =  showString (formatRealFloat FFGeneric d x)
 --
 -- This behaves as 'showFFloat', except that a decimal point
 -- is always guaranteed, even if not needed.
+--
+-- /Since: 4.7.0.0/
 showFFloatAlt    :: (RealFloat a) => Maybe Int -> a -> ShowS
 
 -- | Show a signed 'RealFloat' value
@@ -195,6 +197,8 @@ showFFloatAlt    :: (RealFloat a) => Maybe Int -> a -> ShowS
 --
 -- This behaves as 'showFFloat', except that a decimal point
 -- is always guaranteed, even if not needed.
+--
+-- /Since: 4.7.0.0/
 showGFloatAlt    :: (RealFloat a) => Maybe Int -> a -> ShowS
 
 showFFloatAlt d x =  showString (formatRealFloatAlt FFFixed d True x)
index 8397fc3..4288a60 100644 (file)
@@ -266,6 +266,8 @@ ioe_missingEnvVar name = ioException (IOError Nothing NoSuchThing "getEnv"
 --
 -- Throws `Control.Exception.IOException` if @name@ is the empty string or
 -- contains an equals sign.
+--
+-- /Since: 4.7.0.0/
 setEnv :: String -> String -> IO ()
 setEnv key_ value_
   | null key       = throwIO (mkIOError InvalidArgument "setEnv" Nothing Nothing)
@@ -308,6 +310,8 @@ foreign import ccall unsafe "putenv" c_putenv :: CString -> IO CInt
 --
 -- Throws `Control.Exception.IOException` if @name@ is the empty string or
 -- contains an equals sign.
+--
+-- /Since: 4.7.0.0/
 unsetEnv :: String -> IO ()
 #ifdef mingw32_HOST_OS
 unsetEnv key = withCWString key $ \k -> do
index 1633efe..7d080d9 100644 (file)
@@ -116,6 +116,8 @@ instance Eq (StableName a) where
 
 -- | Equality on 'StableName' that does not require that the types of
 -- the arguments match.
+--
+-- /Since: 4.7.0.0/
 eqStableName :: StableName a -> StableName b -> Bool
 eqStableName (StableName sn1) (StableName sn2) =
        case eqStableName# sn1 sn2 of
index 84ecd89..ec68edb 100644 (file)
@@ -331,7 +331,9 @@ instance (PrintfArg a, HPrintfType r) => HPrintfType (a -> r) where
 -- default 'parseFormat' expects no modifiers: this is the normal
 -- case. Minimal instance: 'formatArg'.
 class PrintfArg a where
+    -- | /Since: 4.7.0.0/
     formatArg :: a -> FieldFormatter
+    -- | /Since: 4.7.0.0/
     parseFormat :: a -> ModifierParser
     parseFormat _ (c : cs) = FormatParse "" c cs
     parseFormat _ "" = errorShortFormat
@@ -398,7 +400,9 @@ instance PrintfArg Double where
 -- type, is not allowable as a typeclass instance. 'IsChar'
 -- is exported for backward-compatibility.
 class IsChar c where
+    -- | /Since: 4.7.0.0/
     toChar :: c -> Char
+    -- | /Since: 4.7.0.0/
     fromChar :: Char -> c
 
 instance IsChar Char where
@@ -409,14 +413,20 @@ instance IsChar Char where
 
 -- | Whether to left-adjust or zero-pad a field. These are
 -- mutually exclusive, with 'LeftAdjust' taking precedence.
+--
+-- /Since: 4.7.0.0/
 data FormatAdjustment = LeftAdjust | ZeroPad
 
 -- | How to handle the sign of a numeric field.  These are
 -- mutually exclusive, with 'SignPlus' taking precedence.
+--
+-- /Since: 4.7.0.0/
 data FormatSign = SignPlus | SignSpace
 
 -- | Description of field formatting for 'formatArg'. See UNIX `printf`(3)
 -- for a description of how field formatting works.
+--
+-- /Since: 4.7.0.0/
 data FieldFormat = FieldFormat {
   fmtWidth :: Maybe Int,       -- ^ Total width of the field.
   fmtPrecision :: Maybe Int,   -- ^ Secondary field width specifier.
@@ -449,6 +459,8 @@ data FieldFormat = FieldFormat {
 -- | The \"format parser\" walks over argument-type-specific
 -- modifier characters to find the primary format character.
 -- This is the type of its result.
+--
+-- /Since: 4.7.0.0/
 data FormatParse = FormatParse {
   fpModifiers :: String,   -- ^ Any modifiers found.
   fpChar :: Char,          -- ^ Primary format character.
@@ -489,26 +501,36 @@ parseIntFormat _ s =
 
 -- | This is the type of a field formatter reified over its
 -- argument.
+--
+-- /Since: 4.7.0.0/
 type FieldFormatter = FieldFormat -> ShowS
 
 -- | Type of a function that will parse modifier characters
 -- from the format string.
+--
+-- /Since: 4.7.0.0/
 type ModifierParser = String -> FormatParse
 
 -- | Substitute a \'v\' format character with the given
 -- default format character in the 'FieldFormat'. A
 -- convenience for user-implemented types, which should
 -- support \"%v\".
+--
+-- /Since: 4.7.0.0/
 vFmt :: Char -> FieldFormat -> FieldFormat
 vFmt c ufmt@(FieldFormat {fmtChar = 'v'}) = ufmt {fmtChar = c}
 vFmt _ ufmt = ufmt
 
 -- | Formatter for 'Char' values.
+--
+-- /Since: 4.7.0.0/
 formatChar :: Char -> FieldFormatter
 formatChar x ufmt =
   formatIntegral (Just 0) (toInteger $ ord x) $ vFmt 'c' ufmt
 
 -- | Formatter for 'String' values.
+--
+-- /Since: 4.7.0.0/
 formatString :: IsChar a => [a] -> FieldFormatter
 formatString x ufmt =
   case fmtChar $ vFmt 's' ufmt of
@@ -532,6 +554,8 @@ fixupMods ufmt m =
       Nothing -> perror "unknown format modifier"
 
 -- | Formatter for 'Int' values.
+--
+-- /Since: 4.7.0.0/
 formatInt :: (Integral a, Bounded a) => a -> FieldFormatter
 formatInt x ufmt =
   let lb = toInteger $ minBound `asTypeOf` x
@@ -543,6 +567,8 @@ formatInt x ufmt =
   formatIntegral m (toInteger x) ufmt'
 
 -- | Formatter for 'Integer' values.
+--
+-- /Since: 4.7.0.0/
 formatInteger :: Integer -> FieldFormatter
 formatInteger x ufmt =
   let m = fixupMods ufmt Nothing in
@@ -582,6 +608,8 @@ formatIntegral m x ufmt0 =
     upcase (s1, s2) = (s1, map toUpper s2)
 
 -- | Formatter for 'RealFloat' values.
+--
+-- /Since: 4.7.0.0/
 formatRealFloat :: RealFloat a => a -> FieldFormatter
 formatRealFloat x ufmt =
   let c = fmtChar $ vFmt 'g' ufmt
@@ -856,21 +884,31 @@ dfmt c p a d =
 
 -- | Raises an 'error' with a printf-specific prefix on the
 -- message string.
+--
+-- /Since: 4.7.0.0/
 perror :: String -> a
 perror s = error $ "printf: " ++ s
 
 -- | Calls 'perror' to indicate an unknown format letter for
 -- a given type.
+--
+-- /Since: 4.7.0.0/
 errorBadFormat :: Char -> a
 errorBadFormat c = perror $ "bad formatting char " ++ show c
 
 errorShortFormat, errorMissingArgument, errorBadArgument :: a
 -- | Calls 'perror' to indicate that the format string ended
 -- early.
+--
+-- /Since: 4.7.0.0/
 errorShortFormat = perror "formatting string ended prematurely"
 -- | Calls 'perror' to indicate that there is a missing
 -- argument in the argument list.
+--
+-- /Since: 4.7.0.0/
 errorMissingArgument = perror "argument list ended prematurely"
 -- | Calls 'perror' to indicate that there is a type
 -- error or similar in the given argument.
+--
+-- /Since: 4.7.0.0/
 errorBadArgument = perror "bad argument"
index 637299a..28bad33 100644 (file)
@@ -73,6 +73,7 @@ numberToInteger (MkNumber base iPart) = Just (val (fromIntegral base) 0 iPart)
 numberToInteger (MkDecimal iPart Nothing Nothing) = Just (val 10 0 iPart)
 numberToInteger _ = Nothing
 
+-- | /Since: 4.7.0.0/
 numberToFixed :: Integer -> Number -> Maybe (Integer, Integer)
 numberToFixed _ (MkNumber base iPart) = Just (val (fromIntegral base) 0 iPart, 0)
 numberToFixed _ (MkDecimal iPart Nothing Nothing) = Just (val 10 0 iPart, 0)
@@ -151,6 +152,7 @@ numberToRational (MkDecimal iPart mFPart mExp)
 lex :: ReadP Lexeme
 lex = skipSpaces >> lexToken
 
+-- | /Since: 4.7.0.0/
 expect :: Lexeme -> ReadP ()
 expect lexeme = do { skipSpaces 
                    ; thing <- lexToken