[Git][ghc/ghc][wip/andreask/expose-overloaded-docs] Reword -fexpose-overloaded-unfoldings docs.

[Andreas Klebinger (@AndreasK)]

Andreas Klebinger pushed to branch wip/andreask/expose-overloaded-docs at Glasgow Haskell Compiler / GHC


Commits:
07e98bde by Andreas Klebinger at 2024-09-23T15:25:07+02:00
Reword -fexpose-overloaded-unfoldings docs.

This should make them slightly clearer. Fixes #24844

- - - - -


1 changed file:

- docs/users_guide/using-optimisation.rst


Changes:

=====================================
docs/users_guide/using-optimisation.rst
=====================================
@@ -531,7 +531,8 @@ as such you shouldn't need to set any of them explicitly. A flag
     * Use of the magic `inline` function to force inlining.
 
 .. ghc-flag:: -fexpose-overloaded-unfoldings
-    :shortdesc: Expose unfoldings carrying constraints, even for very large or recursive functions.
+    :shortdesc: Expose function unfoldings whos type contains constraints,
+        even for very large or recursive functions.
     :type: dynamic
     :reverse: -fno-expose-overloaded-unfoldings
     :category:
@@ -541,19 +542,24 @@ as such you shouldn't need to set any of them explicitly. A flag
     This experimental flag is a slightly less heavy weight alternative
     to :ghc-flag:`-fexpose-all-unfoldings`.
 
-    Instead of exposing all functions it only aims at exposing constrained functions.
+    Instead of exposing all functions it exposes only those functions which
+    contain constraints within their type.
     This is intended to be used for cases where specialization is considered
     crucial but :ghc-flag:`-fexpose-all-unfoldings` imposes too much compile
     time cost.
 
-    Currently this won't expose unfoldings where a type class is hidden under a
-    newtype. That is for cases like: ::
+    This doesn't guarantee *all* functions which might benefit from specialization
+    will be exposed, for example currently this won't expose unfoldings where a
+    type class is hidden under a newtype.
+
+    That is for cases like: ::
 
         newtype NT a = NT (Integral a => a)
 
         foo :: NT a -> T1 -> TR
 
-    GHC won't recognise `foo` as specialisable and won't expose the unfolding
+    GHC won't look under `NT` for constraints and therefore `foo` won't be
+    recognized as specialisable and this flag won't expose the unfolding
     even with :ghc-flag:`-fexpose-overloaded-unfoldings` enabled.
 
     All the other caveats about :ghc-flag:`-fexpose-overloaded-unfoldings`



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/07e98bde2989adb29077bae8e29fe073e5948001

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/07e98bde2989adb29077bae8e29fe073e5948001
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240923/e8a9ce9a/attachment-0001.html>