From 3df1af53d99d2fd07d5553c326712e56ba76c751 Mon Sep 17 00:00:00 2001 From: Rob Rix Date: Tue, 15 Mar 2016 12:43:56 -0400 Subject: [PATCH] Better docs for Data.Adjoined. --- src/Data/Adjoined.hs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/Data/Adjoined.hs b/src/Data/Adjoined.hs index 6d2a6879b..a640baba4 100644 --- a/src/Data/Adjoined.hs +++ b/src/Data/Adjoined.hs @@ -8,7 +8,12 @@ import Data.Bifunctor.These import Data.Coalescent import Data.Sequence as Seq hiding (null) --- | A collection of elements which can be adjoined onto other such collections associatively. +-- | A collection of elements which can be adjoined onto other such collections associatively. There are two big wins with Data.Adjoined: +-- | +-- | 1. Efficient adjoining of lines and concatenation, thanks to its use of Data.Sequence’s `Seq` type. +-- | 2. The Monoid instance guarantees that adjoining cannot touch any lines other than the outermost. +-- | +-- | Since aligning diffs proceeds through the diff tree depth-first, adjoining child nodes and context from right to left, the former is crucial for efficiency, and the latter is crucial for correctness. Prior to using Data.Adjoined, repeatedly adjoining the last line in a node into its parent, and then its grandparent, and so forth, would sometimes cause blank lines to “travel” downwards, ultimately shifting blank lines at the end of nodes down proportionately to the depth in the tree at which they were introduced. newtype Adjoined a = Adjoined { unAdjoined :: Seq a } deriving (Eq, Foldable, Functor, Show, Traversable)