Documented defaults and non-termination issue.

* Added to the docs of `Foldable` type class
  - Mentioned default implementations
  - Made a note about the non-termination issue

* Annotated each default `Foldable` function
  - Noted which function combinations are unsafe

* Added to the docs of `Traversable` type class
  - Mentioned the defaults to be consistent with `Foldable`

* Regenerated docs

Author: LiamGoodacre

docs/Data/Foldable.md

@@ -15,6 +15,17 @@ class Foldable f where
 - `foldl` folds a structure from the left
 - `foldMap` folds a structure by accumulating values in a `Monoid`
 
+Default implementations are provided by the following functions:
+
+- `foldrDefault`
+- `foldlDefault`
+- `foldMapDefaultL`
+- `foldMapDefaultR`
+
+Note: that some combinations of the default implementations are unsafe to
+use together - causing a non-terminating mutually recursive cycle.
+These combinations are documented per function.
+
 ##### Instances
 ``` purescript
 instance foldableArray :: Foldable Array
@@ -36,6 +47,9 @@ foldrDefault :: forall f a b. (Foldable f) => (a -> b -> b) -> b -> f a -> b
 
 A default implementation of `foldr` using `foldMap`
 
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldMapDefaultR`.
+
 #### `foldlDefault`
 
 ``` purescript
@@ -44,6 +58,9 @@ foldlDefault :: forall f a b. (Foldable f) => (b -> a -> b) -> b -> f a -> b
 
 A default implementation of `foldl` using `foldMap`
 
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldMapDefaultL`.
+
 #### `foldMapDefaultL`
 
 ``` purescript
@@ -52,6 +69,9 @@ foldMapDefaultL :: forall f a m. (Foldable f, Monoid m) => (a -> m) -> f a -> m
 
 A default implementation of `foldMap` using `foldl`
 
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldlDefault`.
+
 #### `foldMapDefaultR`
 
 ``` purescript
@@ -60,6 +80,9 @@ foldMapDefaultR :: forall f a m. (Foldable f, Monoid m) => (a -> m) -> f a -> m
 
 A default implementation of `foldMap` using `foldr`
 
+Note: when defining a `Foldable` instance, this function is unsafe to use
+in combination with `foldrDefault`.
+
 #### `fold`
 
 ``` purescript

docs/Data/Traversable.md

@@ -27,6 +27,11 @@ following sense:
 
 - `foldMap f = runConst <<< traverse (Const <<< f)`
 
+Default implementations are provided by the following functions:
+
+- `traverseDefault`
+- `sequenceDefault`
+
 ##### Instances
 ``` purescript
 instance traversableArray :: Traversable Array

src/Data/Foldable.purs

@@ -37,28 +37,51 @@ import Data.Monoid.Multiplicative (Multiplicative(..))
 -- | - `foldr` folds a structure from the right
 -- | - `foldl` folds a structure from the left
 -- | - `foldMap` folds a structure by accumulating values in a `Monoid`
+-- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `foldrDefault`
+-- | - `foldlDefault`
+-- | - `foldMapDefaultL`
+-- | - `foldMapDefaultR`
+-- |
+-- | Note: that some combinations of the default implementations are unsafe to
+-- | use together - causing a non-terminating mutually recursive cycle.
+-- | These combinations are documented per function.
 class Foldable f where
   foldr :: forall a b. (a -> b -> b) -> b -> f a -> b
   foldl :: forall a b. (b -> a -> b) -> b -> f a -> b
   foldMap :: forall a m. (Monoid m) => (a -> m) -> f a -> m
 
 
 -- | A default implementation of `foldr` using `foldMap`
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldMapDefaultR`.
 foldrDefault :: forall f a b. (Foldable f) =>
                 (a -> b -> b) -> b -> f a -> b
 foldrDefault c u xs = runEndo (foldMap (Endo <<< c) xs) u
 
 -- | A default implementation of `foldl` using `foldMap`
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldMapDefaultL`.
 foldlDefault :: forall f a b. (Foldable f) =>
                 (b -> a -> b) -> b -> f a -> b
 foldlDefault c u xs = runEndo (runDual (foldMap (Dual <<< Endo <<< flip c) xs)) u
 
 -- | A default implementation of `foldMap` using `foldl`
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldlDefault`.
 foldMapDefaultL :: forall f a m. (Foldable f, Monoid m) =>
                    (a -> m) -> f a -> m
 foldMapDefaultL f xs = foldl (\acc x -> f x <> acc) mempty xs
 
 -- | A default implementation of `foldMap` using `foldr`
+-- |
+-- | Note: when defining a `Foldable` instance, this function is unsafe to use
+-- | in combination with `foldrDefault`.
 foldMapDefaultR :: forall f a m. (Foldable f, Monoid m) =>
                    (a -> m) -> f a -> m
 foldMapDefaultR f xs = foldr (\x acc -> f x <> acc) mempty xs

src/Data/Traversable.purs

@@ -39,6 +39,11 @@ import Data.Monoid.Conj (Conj(..), runConj)
 -- | `Foldable` instances, in the following sense:
 -- |
 -- | - `foldMap f = runConst <<< traverse (Const <<< f)`
+-- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `traverseDefault`
+-- | - `sequenceDefault`
 class (Functor t, Foldable t) <= Traversable t where
   traverse :: forall a b m. (Applicative m) => (a -> m b) -> t a -> m (t b)
   sequence :: forall a m. (Applicative m) => t (m a) -> m (t a)