Added documentaion comments for textmanip

textmanip/textmanip.go

@@ -2,12 +2,18 @@ package textmanip
 
 import "unicode"
 
+// Dot represents a cursor or text selection. It has a start and end position,
+// referring to where the user began and ended the selection respectively.
 type Dot struct { Start, End int }
 
+// EmptyDot returns a zero-width dot at the specified position.
 func EmptyDot (position int) Dot {
 	return Dot { position, position }
 }
 
+// Canon places the lesser value at the start, and the greater value at the end.
+// Note that a canonized dot does not in all cases correspond directly to the
+// original.
 func (dot Dot) Canon () Dot {
 	if dot.Start > dot.End {
 		return Dot { dot.End, dot.Start }
@@ -16,10 +22,12 @@ func (dot Dot) Canon () Dot {
 	}
 }
 
+// Empty returns whether or not the 
 func (dot Dot) Empty () bool {
 	return dot.Start == dot.End
 }
 
+// Add shifts the dot to the right by the specified amount.
 func (dot Dot) Add (delta int) Dot {
 	return Dot {
 		dot.Start + delta,
@@ -27,6 +35,7 @@ func (dot Dot) Add (delta int) Dot {
 	}
 }
 
+// Add shifts the dot to the left by the specified amount.
 func (dot Dot) Sub (delta int) Dot {
 	return Dot {
 		dot.Start - delta,
@@ -34,6 +43,7 @@ func (dot Dot) Sub (delta int) Dot {
 	}
 }
 
+// Constrain constrains the dot's start and end from zero to length (inclusive).
 func (dot Dot) Constrain (length int) Dot {
 	if dot.Start < 0      { dot.Start = 0 }
 	if dot.Start > length { dot.Start = length}
@@ -42,16 +52,20 @@ func (dot Dot) Constrain (length int) Dot {
 	return dot
 }
 
+// Width returns how many runes the dot spans.
 func (dot Dot) Width () int {
 	dot = dot.Canon()
 	return dot.End - dot.Start
 }
 
+// Slice returns the subset of text that the dot covers.
 func (dot Dot) Slice (text []rune) []rune {
 	dot = dot.Canon().Constrain(len(text))
 	return text[dot.Start:dot.End]
 }
 
+// WordToLeft returns how far away to the left the next word boundary is from a
+// given position.
 func WordToLeft (text []rune, position int) (length int) {
 	if position < 1 { return }
 	if position > len(text) { position = len(text) }
@@ -68,6 +82,8 @@ func WordToLeft (text []rune, position int) (length int) {
 	return
 }
 
+// WordToRight returns how far away to the right the next word boundary is from
+// a given position.
 func WordToRight (text []rune, position int) (length int) {
 	if position < 0 { return }
 	if position > len(text) { position = len(text) }
@@ -84,6 +100,7 @@ func WordToRight (text []rune, position int) (length int) {
 	return
 }
 
+// WordAround returns a dot that surrounds the word at the specified position.
 func WordAround (text []rune, position int) (around Dot) {
 	return Dot {
 		WordToLeft(text, position),
@@ -91,6 +108,9 @@ func WordAround (text []rune, position int) (around Dot) {
 	}
 }
 
+// Backspace deletes the rune to the left of the dot. If word is true, it
+// deletes up until the next word boundary on the left. If the dot is non-empty,
+// it deletes the text inside of the dot.
 func Backspace (text []rune, dot Dot, word bool) (result []rune, moved Dot) {
 	dot = dot.Constrain(len(text))
 	if dot.Empty() {
@@ -109,6 +129,9 @@ func Backspace (text []rune, dot Dot, word bool) (result []rune, moved Dot) {
 	}
 }
 
+// Delete deletes the rune to the right of the dot. If word is true, it deletes
+// up until the next word boundary on the right. If the dot is non-empty, it
+// deletes the text inside of the dot.
 func Delete (text []rune, dot Dot, word bool) (result []rune, moved Dot) {
 	dot = dot.Constrain(len(text))
 	if dot.Empty() {
@@ -131,6 +154,7 @@ func Delete (text []rune, dot Dot, word bool) (result []rune, moved Dot) {
 	}
 }
 
+// Lift removes the section of text inside of the dot, and returns a copy of it.
 func Lift (text []rune, dot Dot) (result []rune, moved Dot, lifted []rune) {
 	dot = dot.Constrain(len(text))
 	if dot.Empty() {
@@ -147,6 +171,8 @@ func Lift (text []rune, dot Dot) (result []rune, moved Dot, lifted []rune) {
 	return
 }
 
+// Type inserts one of more runes into the text at the dot position. If the dot
+// is non-empty, it replaces the text inside of the dot with the new runes.
 func Type (text []rune, dot Dot, characters ...rune) (result []rune, moved Dot) {
 	dot = dot.Constrain(len(text))
 	if dot.Empty() {
@@ -167,6 +193,8 @@ func Type (text []rune, dot Dot, characters ...rune) (result []rune, moved Dot)
 	}
 }
 
+// MoveLeft moves the dot left one rune. If word is true, it moves the dot to
+// the next word boundary on the left.
 func MoveLeft (text []rune, dot Dot, word bool) (moved Dot) {
 	dot = dot.Canon().Constrain(len(text))
 	distance := 0
@@ -180,6 +208,8 @@ func MoveLeft (text []rune, dot Dot, word bool) (moved Dot) {
 	return
 }
 
+// MoveRight moves the dot right one rune. If word is true, it moves the dot to
+// the next word boundary on the right.
 func MoveRight (text []rune, dot Dot, word bool) (moved Dot) {
 	dot = dot.Canon().Constrain(len(text))
 	distance := 0
@@ -193,6 +223,8 @@ func MoveRight (text []rune, dot Dot, word bool) (moved Dot) {
 	return
 }
 
+// SelectLeft moves the end of the dot left one rune. If word is true, it moves
+// the end of the dot to the next word boundary on the left.
 func SelectLeft (text []rune, dot Dot, word bool) (moved Dot) {
 	dot = dot.Constrain(len(text))
 	distance := 1
@@ -203,6 +235,8 @@ func SelectLeft (text []rune, dot Dot, word bool) (moved Dot) {
 	return dot
 }
 
+// SelectRight moves the end of the dot right one rune. If word is true, it
+// moves the end of the dot to the next word boundary on the right.
 func SelectRight (text []rune, dot Dot, word bool) (moved Dot) {
 	dot = dot.Constrain(len(text))
 	distance := 1