Merge pull request #422 from haskellfoundation/GHC-94458

Add documentation for GHC-94458 and GHC-05661

Author: david-christiansen

message-index/messages/GHC-05661/doubleQualified/after/DoubleQualified.hs

@@ -0,0 +1,4 @@
+{-# LANGUAGE ImportQualifiedPost #-}
+module DoubleQualified where
+
+import Prelude qualified

message-index/messages/GHC-05661/doubleQualified/before/DoubleQualified.hs

@@ -0,0 +1,4 @@
+{-# LANGUAGE ImportQualifiedPost #-}
+module DoubleQualified where
+
+import qualified Prelude qualified

message-index/messages/GHC-05661/doubleQualified/index.md

@@ -0,0 +1,15 @@
+---
+title: The module Prelude is incorrectly imported as qualified
+---
+
+In this example, the `qualified` modifier was used both before and after the name of the module which is imported.
+This is not legal syntax, and GHC emits this error message.
+The error can be fixed by removing one of the two occurrences.
+
+```
+messages/GHC-05661/doubleQualified/before/DoubleQualified.hs:4:26: error: [GHC-05661]
+    Multiple occurrences of 'qualified'
+  |
+4 | import qualified Prelude qualified
+  |                          ^^^^^^^^^
+```

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

@@ -0,0 +1,8 @@
+---
+title: Cannot use qualified both before and after the module
+summary: A module cannot be imported using the qualified modifier both before and after the name of the module
+severity: error
+introduced: 9.6.1
+---
+
+With the language extension `ImportQualifiedPost` it is possible to import a module using the `qualified` modifier after the name of the module. But it is not legal to use the `qualified` modifier both before and after the name of the module.

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.