users-guide: Clarify language extension documentation

Over the years the users guide's language extension documentation has
gone through quite a few refactorings. In the process some of the
descriptions have been rendered non-sensical. For instance, the
description of `NoImplicitPrelude` actually describes the semantics of
`ImplicitPrelude`.

To fix this we:

 * ensure that all extensions are named in their "positive" sense (e.g.
   `ImplicitPrelude` rather than `NoImplicitPrelude`).
 * rework the documentation to avoid flag-oriented wording
   like "enable" and "disable"
 * ensure that the polarity of the documentation is consistent with
   reality.

Fixes #23895.

docs/users_guide/expected-undocumented-flags.txt

@@ -9,17 +9,13 @@
 -XAutoDeriveTypeable
 -XDoAndIfThenElse
 -XDoRec
--XImplicitPrelude
 -XJavaScriptFFI
--XMonomorphismRestriction
 -XParallelArrays
--XPatternGuards
 -XPatternSignatures
 -XPolymorphicComponents
 -XRecordPuns
 -XRelaxedLayout
 -XRelaxedPolyRec
--XTraditionalRecordSyntax
 -copy-libs-when-linking
 -dannot-lint
 -dppr-ticks

docs/users_guide/exts/applicative_do.rst

@@ -8,7 +8,7 @@ Applicative do-notation
    single: do-notation; Applicative
 
 .. extension:: ApplicativeDo
-    :shortdesc: Enable Applicative do-notation desugaring
+    :shortdesc: Allow do-notation statements to be desugared via ``Applicative``.
 
     :since: 8.0.1
 

docs/users_guide/exts/arrows.rst

@@ -4,7 +4,7 @@ Arrow notation
 ==============
 
 .. extension:: Arrows
-    :shortdesc: Enable arrow notation extension
+    :shortdesc: Allow arrow notation (e.g. ``proc``)
 
     :since: 6.8.1
 

docs/users_guide/exts/binary_literals.rst

@@ -4,7 +4,7 @@ Binary integer literals
 -----------------------
 
 .. extension:: BinaryLiterals
-    :shortdesc: Enable support for binary literals.
+    :shortdesc: Allow binary literal syntax.
 
     :since: 7.10.1
 

docs/users_guide/exts/constrained_class_methods.rst

@@ -4,8 +4,7 @@ Constrained class method types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: ConstrainedClassMethods
-    :shortdesc: Enable constrained class methods.
-        Implied by :extension:`MultiParamTypeClasses`.
+    :shortdesc: Allow class methods to have non-empty contexts.
 
     :since: 6.8.1
 

docs/users_guide/exts/constraint_kind.rst

@@ -4,7 +4,7 @@ The ``Constraint`` kind
 -----------------------
 
 .. extension:: ConstraintKinds
-    :shortdesc: Enable a kind of constraints.
+    :shortdesc: Allow constraints to be used as types of kind ``Constraint``.
 
     :since: 7.4.1
 

docs/users_guide/exts/data_kinds.rst

@@ -4,7 +4,7 @@ Datatype promotion
 ==================
 
 .. extension:: DataKinds
-    :shortdesc: Enable datatype promotion.
+    :shortdesc: Allow use of data constructors in types.
 
     :since: 7.4.1
 

docs/users_guide/exts/default_signatures.rst

@@ -4,7 +4,7 @@ Default method signatures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DefaultSignatures
-    :shortdesc: Enable default signatures.
+    :shortdesc: Allow default signatures for typeclass methods.
 
     :since: 7.2.1
 

docs/users_guide/exts/derive_any_class.rst

@@ -4,7 +4,7 @@ Deriving any other class
 ------------------------
 
 .. extension:: DeriveAnyClass
-    :shortdesc: Enable deriving for any class.
+    :shortdesc: Allow ``deriving`` syntax to be used for any class.
 
     :since: 7.10.1
 

docs/users_guide/exts/deriving_extra.rst

@@ -50,8 +50,7 @@ Deriving ``Functor`` instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DeriveFunctor
-    :shortdesc: Enable deriving for the Functor class.
-        Implied by :extension:`DeriveTraversable`.
+    :shortdesc: Allow deriving for the ``Functor`` class.
 
     :implied by: :extension:`DeriveTraversable`
     :since: 7.10.1
@@ -246,8 +245,7 @@ Deriving ``Foldable`` instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DeriveFoldable
-    :shortdesc: Enable deriving for the Foldable class.
-        Implied by :extension:`DeriveTraversable`.
+    :shortdesc: Allow deriving for the ``Foldable`` class.
 
     :implied by: :extension:`DeriveTraversable`
     :since: 7.10.1
@@ -389,8 +387,7 @@ Deriving ``Traversable`` instances
 
 
 .. extension:: DeriveTraversable
-    :shortdesc: Enable deriving for the Traversable class.
-        Implies :extension:`DeriveFunctor` and :extension:`DeriveFoldable`.
+    :shortdesc: Allow deriving for the ``Traversable`` class.
 
     :implies: :extension:`DeriveFoldable`, :extension:`DeriveFunctor`
     :implied by: :extension:`GHC2021`
@@ -469,7 +466,7 @@ Deriving ``Data`` instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DeriveDataTypeable
-    :shortdesc: Enable deriving for the ``Data`` class.
+    :shortdesc: Allow deriving for the ``Data`` class.
 
     :since: 6.8.1
     :status: Included in :extension:`GHC2024`, :extension:`GHC2021`
@@ -523,7 +520,7 @@ Deriving ``Lift`` instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DeriveLift
-    :shortdesc: Enable deriving for the Lift class
+    :shortdesc: Allow deriving for the ``Lift`` class
 
     :since: 8.0.1
     :status: Included in :extension:`GHC2024`, :extension:`GHC2021`

docs/users_guide/exts/deriving_strategies.rst

@@ -4,7 +4,7 @@ Deriving strategies
 -------------------
 
 .. extension:: DerivingStrategies
-    :shortdesc: Enables deriving strategies.
+    :shortdesc: Allow use of instance deriving strategies.
 
     :since: 8.2.1
 

docs/users_guide/exts/deriving_via.rst

@@ -4,9 +4,8 @@ Deriving via
 ------------
 
 .. extension:: DerivingVia
-    :shortdesc: Enable deriving instances ``via`` types of the same runtime
+    :shortdesc: Allow deriving instances ``via`` types of the same runtime
         representation.
-        Implies :extension:`DerivingStrategies`.
 
     :implies: :extension:`DerivingStrategies`
 

docs/users_guide/exts/disambiguate_record_fields.rst

@@ -4,8 +4,7 @@ Record field disambiguation
 ---------------------------
 
 .. extension:: DisambiguateRecordFields
-    :shortdesc: Enable record field disambiguation.
-        Implied by :extension:`RecordWildCards`.
+    :shortdesc: Automatically disambiguate some record field references.
 
     :since: 6.8.1
     :implied by: :extension:`RecordWildCards`, :extension:`DuplicateRecordFields`

docs/users_guide/exts/empty_case.rst

@@ -4,7 +4,7 @@ Empty case alternatives
 -----------------------
 
 .. extension:: EmptyCase
-    :shortdesc: Allow empty case alternatives.
+    :shortdesc: Allow ``case`` expressions with no alternatives.
 
     :since: 7.8.1
     :status: Included in :extension:`GHC2024`, :extension:`GHC2021`

docs/users_guide/exts/existential_quantification.rst

@@ -4,7 +4,7 @@ Existentially quantified data constructors
 ------------------------------------------
 
 .. extension:: ExistentialQuantification
-    :shortdesc: Enable liberalised type synonyms.
+    :shortdesc: Allow existentially quantified type variables in types.
 
     :implies: :extension:`ExplicitForAll`
     :since: 6.8.1

docs/users_guide/exts/explicit_forall.rst

@@ -4,9 +4,7 @@ Explicit universal quantification (forall)
 ------------------------------------------
 
 .. extension:: ExplicitForAll
-    :shortdesc: Enable explicit universal quantification.
-        Implied by :extension:`ScopedTypeVariables`, :extension:`LiberalTypeSynonyms`,
-        :extension:`RankNTypes` and :extension:`ExistentialQuantification`.
+    :shortdesc: Allow explicit universal quantification.
 
     :implied by: :extension:`ScopedTypeVariables`, :extension:`LiberalTypeSynonyms`,
         :extension:`RankNTypes`, :extension:`ExistentialQuantification`

docs/users_guide/exts/explicit_namespaces.rst

@@ -4,9 +4,8 @@ Explicit namespaces in import/export
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: ExplicitNamespaces
-    :shortdesc: Enable using the keyword ``type`` to specify the namespace of
-        entries in imports and exports (:ref:`explicit-namespaces`).
-        Implied by :extension:`TypeOperators` and :extension:`TypeFamilies`.
+    :shortdesc: Allow use of the keyword ``type`` to specify the namespace of
+        entries in imports and exports.
 
     :implied by: :extension:`TypeOperators`, :extension:`TypeFamilies`
     :since: 7.6.1

docs/users_guide/exts/extended_literals.rst

@@ -4,7 +4,7 @@ Sized primitive literal syntax
 ------------------------------
 
 .. extension:: ExtendedLiterals
-    :shortdesc: Enable numeric literal postfix syntax for unboxed integers.
+    :shortdesc: Allow numeric literal postfix syntax for unboxed integers.
 
     :since: 9.8.1
 

docs/users_guide/exts/ffi.rst

@@ -8,7 +8,7 @@ Foreign function interface (FFI)
    single: interfacing with native code
 
 .. extension:: ForeignFunctionInterface
-    :shortdesc: Enable foreign function interface.
+    :shortdesc: Allow foreign function interface syntax.
 
     :since: 6.8.1
 
@@ -114,7 +114,7 @@ Unlifted FFI Types
 ~~~~~~~~~~~~~~~~~~
 
 .. extension:: UnliftedFFITypes
-    :shortdesc: Enable unlifted FFI types
+    :shortdesc: Allow the types of foreign imports to contain certain unlifted types.
 
     :since: 6.8.1
 
@@ -282,7 +282,7 @@ Primitive imports
 ~~~~~~~~~~~~~~~~~
 
 .. extension:: GHCForeignImportPrim
-    :shortdesc: Enable prim calling convention. Intended for internal use only.
+    :shortdesc: Allow ``prim`` calling convention. Intended for internal use only.
 
     :since: 6.12.1
 
@@ -310,7 +310,7 @@ Interruptible foreign calls
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: InterruptibleFFI
-    :shortdesc: Enable interruptible FFI.
+    :shortdesc: Allow ``interruptible`` FFI imports.
 
     :since: 7.2.1
 
@@ -394,7 +394,7 @@ The CAPI calling convention
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: CApiFFI
-    :shortdesc: Enable the CAPI calling convention.
+    :shortdesc: Allow ``foreign import``\ s to be declared with the ``capi`` calling convention.
 
     :since: 7.6.1
 

docs/users_guide/exts/field_selectors.rst

@@ -4,7 +4,7 @@ Field selectors
 ---------------
 
 .. extension:: FieldSelectors
-    :shortdesc: Control visibility of field selector functions.
+    :shortdesc: Make record field selector functions visible in expressions.
 
     :since: 9.2.1
     :status: Included in :extension:`GHC2024`, :extension:`GHC2021`, :extension:`Haskell2010`, :extension:`Haskell98`