[commit: ghc] master: Fix documentation and comment issues (5d48f7c)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/5d48f7ce7030ea764446d3ad8cecd60d016f3197/ghc

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

commit 5d48f7ce7030ea764446d3ad8cecd60d016f3197
Author: Cyd Parser <cydparser at gmail.com>
Date:   Tue Oct 31 23:13:50 2017 -0700

    Fix documentation and comment issues


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

5d48f7ce7030ea764446d3ad8cecd60d016f3197
 docs/users_guide/glasgow_exts.rst  | 13 +++++++++----
 libraries/base/Control/Monad/ST.hs |  2 +-
 libraries/base/Data/Traversable.hs |  4 ++--
 libraries/base/GHC/Exception.hs    |  8 ++++----
 4 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 3976bef..a86392f 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -5838,12 +5838,17 @@ information can be seen both as a generalisation of the proposal for
 Odersky, or as a special case of Mark Jones's later framework for
 "improvement" of qualified types. The underlying ideas are also
 discussed in a more theoretical and abstract setting in a manuscript
-[implparam], where they are identified as one point in a general design
+[Jones1999]_, where they are identified as one point in a general design
 space for systems of implicit parameterisation). To start with an
 abstract example, consider a declaration such as: ::
 
        class C a b where ...
 
+.. [Jones1999]
+    "`Exploring the Design Space for Type-based Implicit Parameterization
+    <https://web.cecs.pdx.edu/~mpj/pubs/fdtr.html>`__", Mark P. Jones, Oregon
+    Graduate Institute of Science & Technology, Technical Report, July 1999.
+
 which tells us simply that ``C`` can be thought of as a binary relation on
 types (or type constructors, depending on the kinds of ``a`` and ``b``). Extra
 clauses can be included in the definition of classes to add information
@@ -5853,7 +5858,7 @@ about dependencies between parameters, as in the following examples: ::
        class E a b | a -> b, b -> a where ...
 
 The notation ``a -> b`` used here between the ``|`` and ``where`` symbols —
-not to be confused with a function type — indicates that the a
+not to be confused with a function type — indicates that the ``a``
 parameter uniquely determines the ``b`` parameter, and might be read as "``a``
 determines ``b``." Thus ``D`` is not just a relation, but actually a (partial)
 function. Similarly, from the two dependencies that are included in the
@@ -7028,14 +7033,14 @@ families <http://www.haskell.org/haskellwiki/GHC/Indexed_types>`__.
     and S. Marlow. In Proceedings of “The 32nd Annual
     ACM SIGPLAN-SIGACT Symposium on Principles of
     Programming Languages (POPL'05)”, pages 1-13, ACM
-    Press, 2005)
+    Press, 2005.
 
 .. [AssocTypeSyn2005]
     “`Type Associated Type
     Synonyms <http://www.cse.unsw.edu.au/~chak/papers/CKP05.html>`__\ ”. M.
     Chakravarty, G. Keller, and S. Peyton Jones. In Proceedings of “The
     Tenth ACM SIGPLAN International Conference on Functional Programming”,
-    ACM Press, pages 241-253, 2005).
+    ACM Press, pages 241-253, 2005.
 
 .. [TypeFamilies2008]
     “\ `Type Checking with Open Type
diff --git a/libraries/base/Control/Monad/ST.hs b/libraries/base/Control/Monad/ST.hs
index 8313c2d..6f1dc31 100644
--- a/libraries/base/Control/Monad/ST.hs
+++ b/libraries/base/Control/Monad/ST.hs
@@ -16,7 +16,7 @@
 --
 -- References (variables) that can be used within the @ST@ monad are
 -- provided by "Data.STRef", and arrays are provided by
--- "Data.Array.ST".
+-- [Data.Array.ST](https://hackage.haskell.org/package/array/docs/Data-Array-ST.html).
 
 -----------------------------------------------------------------------------
 
diff --git a/libraries/base/Data/Traversable.hs b/libraries/base/Data/Traversable.hs
index 71a4420..72d88b6 100644
--- a/libraries/base/Data/Traversable.hs
+++ b/libraries/base/Data/Traversable.hs
@@ -198,8 +198,8 @@ Consider
 
 This gives rise to a list-instance of mapM looking like this
 
-  $fTraversable[]_$ctaverse = ...code for traverse on lists...
-       {-# INLINE $fTraversable[]_$ctaverse #-}
+  $fTraversable[]_$ctraverse = ...code for traverse on lists...
+       {-# INLINE $fTraversable[]_$ctraverse #-}
   $fTraversable[]_$cmapM    = $fTraversable[]_$ctraverse
 
 Now the $ctraverse obediently inlines into the RHS of $cmapM, /but/
diff --git a/libraries/base/GHC/Exception.hs b/libraries/base/GHC/Exception.hs
index 6a77e6e..725b864 100644
--- a/libraries/base/GHC/Exception.hs
+++ b/libraries/base/GHC/Exception.hs
@@ -130,13 +130,13 @@ We can now catch a @MismatchedParentheses@ exception as
 @SomeCompilerException@, but not other types, e.g. @IOException@:
 
 @
-*Main> throw MismatchedParentheses `catch` \e -> putStrLn (\"Caught \" ++ show (e :: MismatchedParentheses))
+*Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: MismatchedParentheses))
 Caught MismatchedParentheses
-*Main> throw MismatchedParentheses `catch` \e -> putStrLn (\"Caught \" ++ show (e :: SomeFrontendException))
+*Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: SomeFrontendException))
 Caught MismatchedParentheses
-*Main> throw MismatchedParentheses `catch` \e -> putStrLn (\"Caught \" ++ show (e :: SomeCompilerException))
+*Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: SomeCompilerException))
 Caught MismatchedParentheses
-*Main> throw MismatchedParentheses `catch` \e -> putStrLn (\"Caught \" ++ show (e :: IOException))
+*Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: IOException))
 *** Exception: MismatchedParentheses
 @