**@@ 14,9 14,13 @@ type**
proc diff*[T](itemsOld, itemsNew: openArray[T]): seq[Diff[T]] =
- ## Find the differences between two seqs.
+ ## Find the differences between two `itemsOld` and `itemsNew`.
## Each entry of the returned seq is an instruction describing the
- ## shortest method of changing itemsOld into itemsNew.
+ ## shortest method of changing `itemsOld` into `itemsNew`.
+ ##
+ ## A `Diff` of kind `Insertion` means that a set of tokens were inserted
+ ## into `itemsOld`, `Deletion` means that a set of tokens were removed,
+ ## and `NoChange` means that the subsequence of tokens is identical.
var oldIndexMap: Table[T, seq[int]]
for ix, item in itemsOld:
if item in oldIndexMap:
**@@ 69,9 73,11 @@ proc diff*[T](itemsOld, itemsNew: openArray[T]): seq[Diff[T]] =**
proc stringDiff*(s1, s2: string, seps: set[char] = Newlines): seq[Diff[string]] =
- ## Return the difference between two strings on a line-by-line basis.
+ ## Return the difference between `s1` and `s2` on a line-by-line basis.
## Each entry of the returned seq is an instruction describing the
- ## shortest method of changing s1 into s2.
+ ## shortest method of changing `s1` into `s2`.
+ ##
+ ## See the documentation for `diff` for an explanation of the result.
return diff(split(s1, seps = seps), split(s2, seps = seps))