Support SCC pragmas in declaration context

Not having SCCs at the top level is becoming annoying real quick. For
simplest cases, it's possible to do this transformation:

    f x y = ...
    =>
    f = {-# SCC f #-} \x y -> ...

However, it doesn't work when there's a `where` clause:

    f x y = <t is in scope>
      where t = ...
    =>
    f = {-# SCC f #-} \x y -> <t is out of scope>
      where t = ...

Or when we have a "equation style" definition:

    f (C1 ...) = ...
    f (C2 ...) = ...
    f (C3 ...) = ...
    ...

(usual solution is to rename `f` to `f'` and define a new `f` with a
`SCC`)

This patch implements support for SCC annotations in declaration
contexts. This is now a valid program:

    f x y = ...
      where
        g z = ...
        {-# SCC g #-}
    {-# SCC f #-}

Test Plan: This passes slow validate (no new failures added).

Reviewers: goldfire, mpickering, austin, bgamari, simonmar

Reviewed By: bgamari, simonmar

Subscribers: simonmar, thomie, mpickering

Differential Revision: https://phabricator.haskell.org/D2407

2 files changed, 24 insertions, 3 deletions

diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst
index 1d302ff5bf..5f45bf1002 100644
--- a/docs/users_guide/8.2.1-notes.rst
+++ b/docs/users_guide/8.2.1-notes.rst
@@ -13,6 +13,7 @@ Highlights
 The highlights since the 8.0 branch are:
 
 - TODO FIXME
+- SCC annotations can now be used for declarations.
 
 Full details
 ------------
@@ -32,7 +33,10 @@ Compiler
 
 - Old profiling flags ``-auto-all``, ``-auto``, and ``-caf-all`` are deprecated
   and their usage provokes a compile-time warning.
-  
+
+- Support for adding cost centres to declarations is added. The same `SCC`
+  syntax can be used, in addition to a new form for specifying the cost centre
+  name. See :ref:`scc-pragma` for examples.
 
 GHCi
 ~~~~
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index daae7805d5..20f2a83824 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -199,7 +199,7 @@ to the compiler, it automatically inserts a cost centre annotation
 around every binding not marked INLINE in your program, but you are
 entirely free to add cost centre annotations yourself.
 
-The syntax of a cost centre annotation is ::
+The syntax of a cost centre annotation for expressions is ::
 
     {-# SCC "name" #-} <expression>
 
@@ -210,7 +210,24 @@ extends as far to the right as possible when parsing. (SCC stands for
 "Set Cost Centre"). The double quotes can be omitted if ``name`` is a
 Haskell identifier, for example: ::
 
-    {-# SCC my_function #-} <expression>
+    {-# SCC id #-} <expression>
+
+Cost centre annotations can also appear in the top-level or in a
+declaration context. In that case you need to pass a function name
+defined in the same module or scope with the annotation. Example: ::
+
+    f x y = ...
+      where
+        g z = ...
+        {-# SCC g #-}
+
+    {-# SCC f #-}
+
+If you want to give a cost centre different name than the function name,
+you can pass a string to the annotation ::
+
+    f x y = ...
+    {-# SCC f "cost_centre_name" #-}
 
 Here is an example of a program with a couple of SCCs: ::