Language.Nix.Identifier: better organise module documentation

language-nix/src/Language/Nix/Identifier.hs

@@ -4,9 +4,15 @@
 {-# LANGUAGE TemplateHaskell #-}
 
 module Language.Nix.Identifier
-  ( Identifier, ident, quote, needsQuoting, nixKeywords
+  ( -- * Type-safe Identifiers
+    Identifier, ident
   , parseSimpleIdentifier, parseQuotedIdentifier
-  -- TODO: why do we expose quote?
+    -- * String Predicates
+  , needsQuoting
+    -- * Internals
+    -- TODO: only required by the language-nix test suite, unexport?
+  , nixKeywords
+  , quote
   )
   where
 
@@ -24,10 +30,12 @@ import Text.PrettyPrint.HughesPJClass as PP
 -- (and viewed) with the 'ident' isomorphism. For the sake of convenience,
 -- @Identifier@s are an instance of the 'IsString' class.
 --
--- Reasonable people restrict themselves to identifiers of the form
--- @[a-zA-Z_][a-zA-Z0-9_'-]*@, because these don't need quoting. The
--- methods of the 'Pretty' class can be used to print an identifier with proper
--- quoting:
+-- It is usually wise to only use identifiers of the form
+-- @[a-zA-Z_][a-zA-Z0-9_'-]*@, because these don't need quoting.
+-- Consequently, they can appear almost anywhere in a Nix expression
+-- (whereas quoted identifiers e.g. can't be used in function patterns).
+-- The methods of the 'Pretty' class can be used to print an identifier
+-- with proper quoting:
 --
 -- >>> pPrint (ident # "test")
 -- test
@@ -128,6 +136,7 @@ nixKeywords =
   [ "assert", "with", "if", "then", "else", "let", "in", "rec", "inherit", "or" ]
 
 -- | Helper function to quote a given identifier string if necessary.
+--   Usually, one should use the 'Pretty' instance of 'Identifier' instead.
 --
 -- >>> putStrLn (quote "abc")
 -- abc