doc: Add documentation for -XDoAndIfThenElse

Resolves #18631

Co-authored-by: Richard Eisenberg <rae@cs.brynmawr.edu>

docs/users_guide/conf.py

@@ -36,7 +36,6 @@ nitpick_ignore = [
 
     ("c:type", "bool"),
 
-    ("extension", "DoAndIfThenElse"),
     ("extension", "RelaxedPolyRec"),
 ]
 

docs/users_guide/expected-undocumented-flags.txt

@@ -7,7 +7,6 @@
 -XAlternativeLayoutRule
 -XAlternativeLayoutRuleTransitional
 -XAutoDeriveTypeable
--XDoAndIfThenElse
 -XDoRec
 -XJavaScriptFFI
 -XParallelArrays

docs/users_guide/exts/doandifthenelse.rst

+.. _doandifthenelse:
+
+Do And If Then Else
+============
+
+.. extension:: DoAndIfThenElse
+    :shortdesc: Allow semicolons in ``if`` expressions.
+
+    :status: Included in :extension:`Haskell2010`
+
+    Allow semicolons in ``if`` expressions.
+
+Normally, a conditional is written like this: ``if cond then expr1 else expr2``. With the extension
+:extension:`DoAndIfThenElse`, semicolons are allowed before the ``then`` and also before the ``else``, allowing
+``if cond; then expr1; else expr2``. (You can also include either semicolon on its own.)
+
+Allowing semicolons in the middle of a conditional is useful in connection with layout-controlled
+blocks, like ``do``\ -blocks. This is because GHC invisibly inserts a semicolon between each line of a
+layout-controlled block. Accordingly, with :extension:`DoAndIfThenElse`, we can write code like this ::
+
+  f mb x y = do
+    b <- mb
+    if b
+    then x
+    else y
+
+Without :extension:`DoAndIfThenElse`, the ``then`` and ``else`` lines would have to be indented with respect
+to the rest of the lines in the ``do``\ -block.

docs/users_guide/exts/syntax.rst

@@ -20,6 +20,7 @@ Syntax
     lambda_case
     empty_case
     multiway_if
+    doandifthenelse
     local_fixity_decls
     block_arguments
     typed_holes