Document GHC-63394 (messages from WARNING and DEPRECATED pragmas)

message-index/messages/GHC-63394/example1/after/PartialHead.hs

@@ -0,0 +1,26 @@
+module PartialHead where
+
+import Data.List.NonEmpty (NonEmpty((:|)))
+import qualified Data.List.NonEmpty as NonEmpty
+import Data.Maybe (listToMaybe)
+
+-- Use pattern-matching, handling the empty case explicitly.
+example1 :: Int
+example1  =
+  let list = 1 : 2 : 3 : [] in
+  case list of
+    [] -> 0
+    hd : _ -> hd
+
+-- Use listToMaybe.
+example2 :: Maybe Int
+example2 =
+  let list = 1 : 2 : 3 : [] in
+  listToMaybe list
+
+-- Refactor to use NonEmpty.head.
+example3 :: Int
+example3 =
+  let list :: NonEmpty Int
+      list = 1 :| 2 : 3 : [] in
+  NonEmpty.head list

message-index/messages/GHC-63394/example1/before/PartialHead.hs

@@ -0,0 +1,6 @@
+module PartialHead where
+
+example :: Int
+example =
+  let list = 1 : 2 : 3 : [] in
+  head list

message-index/messages/GHC-63394/example1/index.md

@@ -0,0 +1,15 @@
+---
+title: "`head` is a partial function"
+---
+
+## Error Message
+
+```
+before/PartialHead.hs:6:3: warning: [GHC-63394] [-Wx-partial]
+    In the use of ‘head’
+    (imported from Prelude, but defined in GHC.List):
+    "This is a partial function, it throws an error on empty lists. Use pattern matching or Data.List.uncons instead. Consider refactoring to use Data.List.NonEmpty."
+  |
+6 |   head list
+  |   ^^^^
+```

message-index/messages/GHC-63394/example2/after/PartialTail.hs

@@ -0,0 +1,25 @@
+module PartialTail where
+
+import Data.List.NonEmpty (NonEmpty((:|)))
+import qualified Data.List.NonEmpty as NonEmpty
+
+-- Replace `tail` with `drop 1`.
+example1 :: [Int]
+example1 =
+  let list = 1 : 2 : 3 : [] in
+  drop 1 list
+
+-- Use pattern-matching.
+example2 :: [Int]
+example2  =
+  let list = 1 : 2 : 3 : [] in
+  case list of
+    [] -> []
+    _ : xs -> xs
+
+-- Refactor to use NonEmpty.tail.
+example3 :: [Int]
+example3 =
+  let list :: NonEmpty Int
+      list = 1 :| 2 : 3 : [] in
+  NonEmpty.tail list

message-index/messages/GHC-63394/example2/before/PartialTail.hs

@@ -0,0 +1,6 @@
+module PartialTail where
+
+example :: [Int]
+example =
+  let list = 1 : 2 : 3 : [] in
+  tail list

message-index/messages/GHC-63394/example2/index.md

@@ -0,0 +1,15 @@
+---
+title: "`tail` is a partial function"
+---
+
+## Error Message
+
+```
+PartialTail.hs:6:3: warning: [GHC-63394] [-Wx-partial]
+    In the use of ‘tail’
+    (imported from Prelude, but defined in GHC.List):
+    "This is a partial function, it throws an error on empty lists. Replace it with drop 1, or use pattern matching or Data.List.uncons instead. Consider refactoring to use Data.List.NonEmpty."
+  |
+6 |   tail list
+  |   ^^^^
+```

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

@@ -0,0 +1,21 @@
+---
+title: Messages from WARNING and DEPRECATED pragmas
+summary: Warning or deprecation message attached to a function, class, type, or module in a library
+severity: warning
+introduced: 9.6.1
+---
+
+Libraries may attach warning messages to functions and other entities they
+export to appear when they are used. Common use cases include deprecated
+functions and partial functions (such as `head` and `tail`).
+
+Those messages are declared using the pragmas `{-# WARNING ... #-}` and
+`{-# DEPRECATED ... #-}`.
+For more information, [see the GHC user's guide][users-guide].
+
+[users-guide]: https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/pragmas.html#warning-and-deprecated-pragmas
+
+```haskell
+{-# WARNING in "x-partial" head "This function is partial..." #-}
+head :: [a] -> a
+```