users-guide: Document deprecation of -funfolding-keeness-factor

See #15304.

docs/users_guide/9.0.1-notes.rst

@@ -248,6 +248,13 @@ Compiler
   default, as proposed in `GHC proposal #314
   <https://github.com/ghc-proposals/ghc-proposals/pull/314>`_
 
+- The ``-funfolding-keeness-factor`` flag has been deprecated as its scaling
+  strategy resulted in unreasonably large discounts in some cases (see
+  :ghc-ticket:`15304`). Users who previously used this flag to suggest
+  more aggressive inlining are advised to look at
+  :ghc-flag:`-funfolding-use-threshold=⟨n⟩` or use :pragma:`INLINE` pragmas to
+  more precisely force inlining.
+
 GHCi
 ~~~~
 

docs/users_guide/expected-undocumented-flags.txt

@@ -82,7 +82,6 @@
 -fspecialize-aggressively
 -fth
 -ftype-function-depth
--funfolding-keeness-factor
 -fuse-rpaths
 -fversion-macros
 -fvia-c

docs/users_guide/using-optimisation.rst

@@ -1399,6 +1399,15 @@ by saying ``-fno-wombat``.
 
     How eager should the compiler be to inline functions?
 
+.. ghc-flag:: -funfolding-keeness-factor=⟨n⟩
+    :shortdesc: This has been deprecated in GHC 9.0.1.
+    :type: dynamic
+    :category:
+
+    This factor was deprecated in GHC 9.0.1. See :ghc-ticket:`15304` for
+    details. Users who need to control inlining should rather consider
+    :ghc-flag:`-funfolding-use-threshold=⟨n⟩`.
+
 .. ghc-flag:: -funfolding-use-threshold=⟨n⟩
     :shortdesc: *default: 80.* Tweak unfolding settings.
     :type: dynamic