Add documentation for GHC-94458

Author: David Binder

message-index/messages/GHC-94458/illegalHaddockComment/after/IllegalHaddockComment.hs

@@ -0,0 +1,8 @@
+module IllegalHaddockComment where
+
+main = print (fizz ++ buzz)
+  where
+    -- The sound of a refreshing beverage.
+    fizz = "fizz"
+    -- The sound of an annoying fly.
+    buzz = "buzz"

message-index/messages/GHC-94458/illegalHaddockComment/before/IllegalHaddockComment.hs

@@ -0,0 +1,8 @@
+module IllegalHaddockComment where
+
+main = print (fizz ++ buzz)
+  where
+    -- | The sound of a refreshing beverage.
+    fizz = "fizz"
+    -- | The sound of an annoying fly.
+    buzz = "buzz"

message-index/messages/GHC-94458/illegalHaddockComment/index.md

@@ -0,0 +1,21 @@
+---
+title: Illegal Haddock comments for definitions in where clause
+---
+
+In this example, the user tried to document the two identifiers "fizz" and "buzz" that are introduced in a local where clause.
+Since these identifiers are not part of the public API, a warning is emitted that Haddock comments are not allowed in that place.
+A normal comment can be used instead.
+
+```
+messages/GHC-94458/illegalHaddockComment/before/IllegalHaddockComment.hs:5:5: warning: [GHC-94458] [-Winvalid-haddock]
+    A Haddock comment cannot appear in this position and will be ignored.
+  |
+5 |     -- | The sound of a refreshing beverage.
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+messages/GHC-94458/illegalHaddockComment/before/IllegalHaddockComment.hs:7:5: warning: [GHC-94458] [-Winvalid-haddock]
+    A Haddock comment cannot appear in this position and will be ignored.
+  |
+7 |     -- | The sound of an annoying fly.
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```

message-index/messages/GHC-94458/index.md

@@ -0,0 +1,9 @@
+---
+title: Illegal position of Haddock comment
+summary: A Haddock comment appears in an illegal position
+severity: warning
+flag: -Winvalid-haddock
+introduced: 9.6.1
+---
+
+Haddock comments are used to document entities of Haskell programs, and are used to generate API documentation which can be displayed on Hackage or as tooltips in editors. This error is emitted when a Haddock comment is attached to an entity that cannot be documented this way. A normal comment should be used instead.