Local edits

src/Diagrams.hs

@@ -6,13 +6,15 @@
 -- License     :  BSD-style (see LICENSE)
 -- Maintainer  :  [email protected]
 --
--- This module only contains exports defined in @diagrams-lib@ or
--- @diagrams-core@. This module can be used if you want to avoid some
--- potential conflicts with other modules, but importing
--- "Diagrams.Prelude" (which includes re-exports from other packages)
--- is often more convenient.
+-- This module only contains exports defined in the @diagrams@ package
+-- itself. This module can be used if you want to avoid some potential
+-- conflicts with other modules, but importing "Diagrams.Prelude"
+-- (which includes re-exports from other packages) is often more
+-- convenient.
+--
+-- Notable omissions from the this module to avoid potential comflicts
+-- include:
 --
--- Notable emmitions from the this module to avoid potential comflicts:
 --   - "Diagrams.TwoD.Image"
 --   - "Diagrams.TwoD.Text"
 --
@@ -30,10 +32,6 @@ module Diagrams
 
   , named
   , localize
-  , styles
-  , leafs
-  , releaf
-  , down
 
     -- * Subdiagrams
   , SubDiagram

src/Diagrams/Combinators.hs

@@ -95,10 +95,11 @@ pad :: (HasLinearMap v, OrderedField n)
 pad s = modEnvelope (scale s)
 {-# INLINE pad #-}
 
--- | @frame s@ increases the envelope of a diagram by and absolute
---   amount @s@, s is in the local units of the diagram. This function
---   is similar to @pad@, only it takes an absolute quantity and
---   pre-centering should not be necessary.
+-- | @frame s@ increases the envelope of a diagram by an absolute
+--   amount @s@ in every direction, measured in the local units of the
+--   diagram. This function is similar to @pad@, but it expands by an
+--   absolute rather than a relative amount, and the result does not
+--   depend on the local origin of the diagram.
 frame :: (Ord n, Fractional n) => n -> QDiagram v n m -> QDiagram v n m
 frame s = modEnvelope $ onEnvelope (\f x -> inflate (f x))
   where

src/Diagrams/Types.hs

@@ -16,16 +16,16 @@
 
 -----------------------------------------------------------------------------
 -- |
--- Module      :  Diagrams.Core.Types
+-- Module      :  Diagrams.Types
 -- Copyright   :  (c) 2011-2016 diagrams-core team (see LICENSE)
 -- License     :  BSD-style (see LICENSE)
 -- Maintainer  :  [email protected]
 --
 -- The core library of primitives forming the basis of an embedded
 -- domain-specific language for describing and rendering diagrams.
 --
--- "Diagrams.Core.Types" defines types and classes for
--- primitives, diagrams, and backends.
+-- "Diagrams.Types" defines types and classes for primitives,
+-- diagrams, and backends.
 --
 -----------------------------------------------------------------------------
 
@@ -56,16 +56,19 @@ module Diagrams.Types
     --   "Diagrams.Combinators" and "Diagrams.TwoD.Combinators"
     --   from the diagrams-lib package.
 
-    -- ** Modifying diagrams
-    -- * Names
+    -- * Modifying diagrams
+    -- ** Names
   , named
   , localize
-  , styles
+
+    -- ** Leaves
   , leafs
   , releaf
+
+    -- ** Down annotations
   , down
 
-    -- *** Replaceing up annotations
+    -- ** Replacing up annotations
   , modEnvelope
   , replaceEnvelope
   , modTrace
@@ -153,15 +156,17 @@ instance (Typeable n, RealFloat n) => TypeableFloat n
 -- backends.  However, not every backend must be able to render every
 -- type of primitive.
 
--- | A value of type @Prim b v n@ is an opaque (existentially quantified)
---   primitive which backend @b@ knows how to render in vector space @v@.
+-- | A value of type @Prim v n@ is an opaque (existentially quantified)
+--   primitive which lives in vector space @v@ over the scalar type @n@.
 data Prim v n where
   Prim :: Typeable p => p -> Prim (V p) (N p)
 
 type instance V (Prim v n) = v
 type instance N (Prim v n) = n
 
--- | Prism onto a 'Prim'.
+-- | Prism onto a 'Prim'.  You must correctly guess (or already know
+--   by some other means) the type @p@ in order to access the value
+--   wrapped inside the 'Prim'.
 _Prim :: (InSpace v n p, Typeable p) => Prism' (Prim v n) p
 _Prim = prism' Prim (\(Prim p) -> cast p)
 {-# INLINE _Prim #-}
@@ -238,12 +243,13 @@ upDiagram :: UpAnnots v n m -> QDiagram v n m
 upDiagram = QD . T.leafU
 {-# INLINE upDiagram #-}
 
--- | Construct a 'upDiagram' by apply a function to the empty up
+-- | Construct a 'upDiagram' by applying a function to the empty up
 --   annotations.
 upWith :: Monoid m => (UpAnnots v n m -> UpAnnots v n m) -> QDiagram v n m
 upWith f = upDiagram (f emptyUp)
 {-# INLINE upWith #-}
 
+-- | Convenience function for applying a down annotation.
 down
   :: forall v n m
   . (Traversable v, Additive v, Floating n)
@@ -288,12 +294,6 @@ named
   => nm -> Traversal' (QDiagram v n m) (QDiagram v n m)
 named (toName -> Name ns) = _Wrapped' . T.traverseSub ns . _Unwrapped'
 
--- | Traversal over the styles of each leaf.
-styles
-  :: (HasLinearMap v, OrderedField n)
-  => Traversal' (QDiagram v n m) (Style v n)
-styles = _Wrapped . T.downs . downStyle
-
 leafs
   :: (HasLinearMap v, OrderedField n)
   => Traversal' (QDiagram v n m) (QDiagram v n m)