add Text doc

text/text.go

@@ -37,8 +37,39 @@ func RangeTable(table *unicode.RangeTable) []rune {
 	return runes
 }
 
+// Text allows text drawing.
+//
+// To create a Text object, use the New constructor:
+//   txt := text.New(face, text.ASCII)
+//
+// As suggested by the constructor, a Text object is always associated with one font face and a
+// fixed set of runes. For example, the Text we create above can draw text using the font face
+// contained in the `face` variable and is capable of drawing ASCII characters.
+//
+// Here we create a Text object which can draw ASCII and Katakana characters:
+//   txt := text.New(face, text.ASCII, text.RangeTable(unicode.Katakana))
+//
+// Similarly to IMDraw, Text functions as a buffer. It implements io.Writer interface, so writing
+// text to it is really simple:
+//   fmt.Print(txt, "Hello, world!")
+//
+// Finally, if we want the written text to show up on some other Target, we can draw it:
+//   txt.Draw(target)
+//
+// Text exports two important fields: Orig and Dot. Dot is the position where the next character
+// will be written. Dot is automatically moved when writing to a Text object, but you can also
+// manipulate it manually. Orig specifies the text origin, usually the top-left dot position. Dot is
+// always aligned to Orig when writing newlines.
+//
+// To reset the Dot to the Orig, just assign it:
+//   txt.Dot = txt.Orig
 type Text struct {
+	// Orig specifies the text origin, usually the top-left dot position. Dot is always aligned
+	// to Orig when writing newlines.
 	Orig pixel.Vec
+
+	// Dot is the position where the next character will be written. Dot is automatically moved
+	// when writing to a Text object, but you can also manipulate it manually
 	Dot pixel.Vec
 
 	atlas *Atlas
@@ -59,6 +90,21 @@ type Text struct {
 	dirty  bool
 }
 
+// New creates a new Text capable of drawing runes contained in the provided rune sets, plus
+// unicode.ReplacementChar using the provided font.Face.
+//
+// Do not destroy or close the font.Face after creating a Text. Although Text caches most of the
+// stuff (pre-drawn glyphs, etc.), it still uses the face for a few things.
+//
+// Here we create a Text capable of drawing ASCII characters using the Go Regular font.
+//   ttf, err := truetype.Parse(goregular.TTF)
+//   if err != nil {
+//       panic(err)
+//   }
+//   face := truetype.NewFace(ttf, &truetype.Options{
+//       Size: 14,
+//   })
+//   txt := text.New(face, text.ASCII)
 func New(face font.Face, runeSets ...[]rune) *Text {
 	runes := []rune{unicode.ReplacementChar}
 	for _, set := range runeSets {
@@ -89,10 +135,13 @@ func New(face font.Face, runeSets ...[]rune) *Text {
 	return txt
 }
 
+// Atlas returns the underlying Text's Atlas containing all of the pre-drawn glyphs. The Atlas is
+// also useful for getting values such as the recommended line height.
 func (txt *Text) Atlas() *Atlas {
 	return txt.atlas
 }
 
+// SetMatrix sets a Matrix by which the text will be transformed before drawing to another Target.
 func (txt *Text) SetMatrix(m pixel.Matrix) {
 	if txt.mat != m {
 		txt.mat = m
@@ -100,6 +149,7 @@ func (txt *Text) SetMatrix(m pixel.Matrix) {
 	}
 }
 
+// SetColorMask sets a color by which the text will be masked before drawingto another Target.
 func (txt *Text) SetColorMask(c color.Color) {
 	rgba := pixel.ToRGBA(c)
 	if txt.col != rgba {
@@ -108,10 +158,14 @@ func (txt *Text) SetColorMask(c color.Color) {
 	}
 }
 
+// Bounds returns the bounding box of the text currently written to the Text excluding whitespace.
+//
+// If the Text is empty, a zero rectangle is returned.
 func (txt *Text) Bounds() pixel.Rect {
 	return txt.bounds
 }
 
+// BoundsOf returns the bounding box of s if it was to be written to the Text right now.
 func (txt *Text) BoundsOf(s string) pixel.Rect {
 	dot := txt.Dot
 	prevR := txt.prevR
@@ -139,6 +193,7 @@ func (txt *Text) BoundsOf(s string) pixel.Rect {
 	return bounds
 }
 
+// Color sets the text color. This does not affect any previously written text.
 func (txt *Text) Color(c color.Color) {
 	rgba := pixel.ToRGBA(c)
 	for i := range txt.glyph {
@@ -146,14 +201,18 @@ func (txt *Text) Color(c color.Color) {
 	}
 }
 
+// LineHeight sets the vertical distance between two lines of text. This does not affect any
+// previously written text.
 func (txt *Text) LineHeight(height float64) {
 	txt.lineHeight = height
 }
 
+// TabWidth sets the horizontal tab width. Tab characters will align to the multiples of this width.
 func (txt *Text) TabWidth(width float64) {
 	txt.tabWidth = width
 }
 
+// Clear removes all written text from the Text.
 func (txt *Text) Clear() {
 	txt.prevR = -1
 	txt.bounds = pixel.Rect{}
@@ -161,24 +220,30 @@ func (txt *Text) Clear() {
 	txt.dirty = true
 }
 
+// Write writes a slice of bytes to the Text. This method never fails, always returns len(p), nil.
 func (txt *Text) Write(p []byte) (n int, err error) {
 	txt.buf = append(txt.buf, p...)
 	txt.drawBuf()
 	return len(p), nil
 }
 
+// WriteString writes a string to the Text. This method never fails, always returns len(s), nil.
 func (txt *Text) WriteString(s string) (n int, err error) {
 	txt.buf = append(txt.buf, s...)
 	txt.drawBuf()
 	return len(s), nil
 }
 
+// WriteByte writes a byte to the Text. This method never fails, always returns nil.
+//
+// Writing a multi-byte rune byte-by-byte is perfectly supported.
 func (txt *Text) WriteByte(c byte) error {
 	txt.buf = append(txt.buf, c)
 	txt.drawBuf()
 	return nil
 }
 
+// WriteRune writes a rune to the Text. This method never fails, always returns utf8.RuneLen(r), nil.
 func (txt *Text) WriteRune(r rune) (n int, err error) {
 	var b [4]byte
 	n = utf8.EncodeRune(b[:], r)
@@ -187,6 +252,8 @@ func (txt *Text) WriteRune(r rune) (n int, err error) {
 	return n, nil
 }
 
+// Draw draws all text written to the Text to the provided Target. The text is transformed by the
+// Text's matrix and color mask.
 func (txt *Text) Draw(t pixel.Target) {
 	if txt.dirty {
 		txt.trans.SetLen(txt.tris.Len())