[commit: ghc] wip/tdammers-7258: Document readField / readSymField (ad349f0)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/tdammers-7258
Link       : http://ghc.haskell.org/trac/ghc/changeset/ad349f0de4372b8ef887ab83a659429cb7f260c8/ghc

>---------------------------------------------------------------

commit ad349f0de4372b8ef887ab83a659429cb7f260c8
Author: Tobias Dammers <tdammers at gmail.com>
Date:   Thu Oct 19 16:31:13 2017 +0200

    Document readField / readSymField


>---------------------------------------------------------------

ad349f0de4372b8ef887ab83a659429cb7f260c8
 libraries/base/GHC/Read.hs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/libraries/base/GHC/Read.hs b/libraries/base/GHC/Read.hs
index e69e4a0..2d8ee3d 100644
--- a/libraries/base/GHC/Read.hs
+++ b/libraries/base/GHC/Read.hs
@@ -361,6 +361,12 @@ choose sps = foldr ((+++) . try_one) pfail sps
                                     L.Symbol s' | s==s' -> p
                                     _other              -> pfail }
 
+-- See Note [Why readField]
+
+-- | 'Read' parser for a record field, of the form @fieldName=value at . The
+-- @fieldName@ must be an alphanumeric identifier; for symbols (operator-style)
+-- field names, e.g. @(#)@, use 'readSymField'). The second argument is a
+-- parser for the field value.
 readField :: String -> ReadPrec a -> ReadPrec a
 readField fieldName readVal = do
         expectP (L.Ident fieldName)
@@ -368,6 +374,12 @@ readField fieldName readVal = do
         readVal
 {-# NOINLINE readField #-}
 
+-- See Note [Why readField]
+
+-- | 'Read' parser for a symbol record field, of the form @(###)=value@ (where
+-- @###@ is the field name). The field name must be a symbol (operator-style),
+-- e.g. @(#)@. For regular (alphanumeric) field names, use 'readField'. The
+-- second argument is a parser for the field value.
 readSymField :: String -> ReadPrec a -> ReadPrec a
 readSymField fieldName readVal = do
         expectP (L.Punc "(")
@@ -377,6 +389,22 @@ readSymField fieldName readVal = do
         readVal
 {-# NOINLINE readSymField #-}
 
+
+-- Note [Why readField]
+--
+-- Previousy, the code for automatically deriving Read instance (in
+-- typecheck/TcGenDeriv.hs) would generate inline code for parsing fields;
+-- this, however, turned out to produce massive amounts of intermediate code,
+-- and produced a considerable performance hit in the code generator.
+-- Since Read instances are not generally supposed to be perfomance critical,
+-- the readField and readSymField functions have been factored out, and the
+-- code generator now just generates calls rather than manually inlining the
+-- parsers. For large record types (e.g. 500 fields), this produces a
+-- significant performance boost.
+--
+-- See also Trac #14364.
+
+
 --------------------------------------------------------------
 -- Simple instances of Read
 --------------------------------------------------------------