Add module level documentation for Unsafe modules

Author: Shimuuar

vector/src/Data/Vector.hs

@@ -16,7 +16,7 @@
 -- Stability   : experimental
 -- Portability : non-portable
 --
--- A library for boxed vectors (that is, polymorphic arrays capable of
+-- A library for lazy boxed vectors (that is, polymorphic arrays capable of
 -- holding any Haskell value). The vectors come in two flavours:
 --
 --  * mutable

vector/src/Data/Vector/Mutable/Unsafe.hs

@@ -5,6 +5,12 @@
 {-# LANGUAGE RoleAnnotations #-}
 {-# LANGUAGE TypeFamilies #-}
 -- |
+-- This module exposes internal representation of mutable lazy boxed
+-- vector and functions that work on that representation directly (as
+-- opposed to using 'G.MVector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety
 module Data.Vector.Mutable.Unsafe
   ( MVector(..)
   , IOVector

vector/src/Data/Vector/Primitive/Mutable/Unsafe.hs

@@ -5,6 +5,12 @@
 {-# LANGUAGE RoleAnnotations #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 -- |
+-- This module exposes internal representation of mutable vectors backed by
+-- single 'ByteArray' and functions that work on that representation
+-- directly (as opposed to using 'G.Vector' API).
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety.
 module Data.Vector.Primitive.Mutable.Unsafe
   ( MVector(..)
   , IOVector

vector/src/Data/Vector/Primitive/Unsafe.hs

@@ -5,6 +5,12 @@
 {-# LANGUAGE RoleAnnotations #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 -- |
+-- This module exposes internal representation of vectors backed by
+-- single 'ByteArray' and functions that work on that representation
+-- directly (as opposed to using 'G.Vector' API).
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety.
 module Data.Vector.Primitive.Unsafe
   ( -- * Mutable vector
     Vector(..)

vector/src/Data/Vector/Storable/Mutable/Unsafe.hs

@@ -5,6 +5,12 @@
 {-# LANGUAGE RoleAnnotations #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 -- |
+-- This module exposes internal representation of mutable vectors
+-- based on 'Storable' and functions that work on that representation
+-- directly (as opposed to using 'G.Vector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety.
 module Data.Vector.Storable.Mutable.Unsafe
   ( MVector(..)
   , IOVector

vector/src/Data/Vector/Storable/Unsafe.hs

@@ -6,6 +6,12 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeFamilies #-}
 -- |
+-- This module exposes internal representation of vectors based on
+-- 'Storable' and functions that work on that representation directly
+-- (as opposed to using 'G.Vector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety.
 module Data.Vector.Storable.Unsafe
   ( Vector(..)
   , unsafeCoerceVector

vector/src/Data/Vector/Strict/Mutable/Unsafe.hs

@@ -7,6 +7,12 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 -- |
+-- This module exposes internal representation of mutable strict boxed
+-- vector and functions that work on that representation directly (as
+-- opposed to using 'G.MVector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety
 module Data.Vector.Strict.Mutable.Unsafe
   ( MVector(..)
   , IOVector

vector/src/Data/Vector/Strict/Unsafe.hs

@@ -8,6 +8,12 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
 -- |
+-- This module exposes internal representation of strict boxed vector
+-- and functions that work on that representation directly (as opposed
+-- to using 'G.Vector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety
 module Data.Vector.Strict.Unsafe
   ( Vector(..)
     -- * Vector conversions

vector/src/Data/Vector/Unboxed/Unsafe.hs

@@ -12,7 +12,7 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE DerivingVia #-}
 -- |
--- Module      : Data.Vector.Unboxed.Base
+-- Module      : Data.Vector.Unboxed.Unsafe
 -- Copyright   : (c) Roman Leshchinskiy 2009-2010
 --                   Alexey Kuleshevich 2020-2022
 --                   Aleksey Khudyakov 2020-2022
@@ -23,8 +23,14 @@
 -- Stability   : experimental
 -- Portability : non-portable
 --
--- Adaptive unboxed vectors: basic implementation.
-
+-- Adaptive unboxed vectors. This module exposes internal
+-- representation for all unboxed vectors. Both pure and mutable
+-- vectors are exposed from this module.
+--
+-- Note that working with internal representation is generally unsafe
+-- and may violate memory safety. Data family constructors which are
+-- safe exposed in "Data.Vector.Unboxed" and
+-- "Data.Vector.Unboxed.Mutable" modules.
 module Data.Vector.Unboxed.Unsafe (
   MVector(..), IOVector, STVector, Vector(..), Unbox,
   UnboxViaPrim(..), UnboxViaStorable(..), As(..), IsoUnbox(..),

vector/src/Data/Vector/Unsafe.hs

@@ -5,6 +5,12 @@
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE TypeFamilies #-}
 -- |
+-- This module exposes internal representation of lazy boxed vector
+-- and functions that work on that representation directly (as opposed
+-- to using 'G.Vector' API.
+--
+-- Note that working with internal representation of vector is
+-- generally unsafe and may violate memory safety
 module Data.Vector.Unsafe
   ( Vector(..)
     -- * Array conversions
@@ -44,7 +50,7 @@ import qualified Data.Traversable as Traversable
 import qualified GHC.Exts as Exts (IsList(..))
 
 
--- | Boxed vectors, supporting efficient slicing.
+-- | Lazy boxed vectors, supporting efficient slicing.
 data Vector a = Vector {-# UNPACK #-} !Int
                        {-# UNPACK #-} !Int
                        {-# UNPACK #-} !(Array a)