Improve StringBuffer and FastString docs

This area of code contains a lot of unsafe functionality, so it might be
worth documenting to reduce the risk of misuse.

Test Plan: inspection

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2872

1 files changed, 13 insertions, 0 deletions

diff --git a/compiler/utils/FastString.hs b/compiler/utils/FastString.hs
index 8f76584875..8d1bbb5c67 100644
--- a/compiler/utils/FastString.hs
+++ b/compiler/utils/FastString.hs
@@ -23,6 +23,10 @@
 --   * Outputing them is fast.
 --   * Generated by 'sLit'.
 --   * Turn into 'Outputable.SDoc' with 'Outputable.ptext'
+--   * Requires manual memory management.
+--     Improper use may lead to memory leaks or dangling pointers.
+--   * It assumes Latin-1 as the encoding, therefore it cannot represent
+--     arbitrary Unicode strings.
 --
 -- Use 'LitString' unless you want the facilities of 'FastString'.
 module FastString
@@ -560,14 +564,19 @@ hPutFS handle fs = BS.hPut handle $ fastStringToByteString fs
 -- -----------------------------------------------------------------------------
 -- LitStrings, here for convenience only.
 
+-- | A 'LitString' is a pointer to some null-terminated array of bytes.
 type LitString = Ptr Word8
 --Why do we recalculate length every time it's requested?
 --If it's commonly needed, we should perhaps have
 --data LitString = LitString {-#UNPACK#-}!Addr# {-#UNPACK#-}!Int#
 
+-- | Wrap an unboxed address into a 'LitString'.
 mkLitString# :: Addr# -> LitString
 mkLitString# a# = Ptr a#
 
+-- | Encode a 'String' into a newly allocated 'LitString' using Latin-1
+-- encoding.  The original string must not contain non-Latin-1 characters
+-- (above codepoint @0xff@).
 {-# INLINE mkLitString #-}
 mkLitString :: String -> LitString
 mkLitString s =
@@ -583,9 +592,13 @@ mkLitString s =
    return p
  )
 
+-- | Decode a 'LitString' back into a 'String' using Latin-1 encoding.
+-- This does not free the memory associated with 'LitString'.
 unpackLitString :: LitString -> String
 unpackLitString (Ptr p) = unpackCString# p
 
+-- | Compute the length of a 'LitString', which must necessarily be
+-- null-terminated.
 lengthLS :: LitString -> Int
 lengthLS = ptrStrLength