fix many bugs in doc

data.go

@@ -8,8 +8,8 @@ import (
 	"math"
 )
 
-// TrianglesData specifies a list of Triangles vertices with three common properties: Position,
-// Color and Texture.
+// TrianglesData specifies a list of Triangles vertices with three common properties:
+// TrianglesPosition, TrianglesColor and TrianglesPicture.
 type TrianglesData []struct {
 	Position  Vec
 	Color     NRGBA
@@ -20,7 +20,7 @@ type TrianglesData []struct {
 // MakeTrianglesData creates TrianglesData of length len initialized with default property values.
 //
 // Prefer this function to make(TrianglesData, len), because make zeros them, while this function
-// does a correct intialization.
+// does the correct intialization.
 func MakeTrianglesData(len int) *TrianglesData {
 	td := &TrianglesData{}
 	td.SetLen(len)
@@ -35,7 +35,7 @@ func (td *TrianglesData) Len() int {
 // SetLen resizes TrianglesData to len, while keeping the original content.
 //
 // If len is greater than TrianglesData's current length, the new data is filled with default
-// values ((0, 0), white, (-1, -1)).
+// values ((0, 0), white, (0, 0), 0).
 func (td *TrianglesData) SetLen(len int) {
 	if len > td.Len() {
 		needAppend := len - td.Len()

geometry.go

@@ -83,7 +83,7 @@ func (u Vec) Angle() float64 {
 	return cmplx.Phase(complex128(u))
 }
 
-// Unit returns a vector of length 1 with the same angle as u.
+// Unit returns a vector of length 1 facing the direction of u (has the same angle).
 func (u Vec) Unit() Vec {
 	return u / V(u.Len(), 0)
 }
@@ -93,7 +93,7 @@ func (u Vec) Scaled(c float64) Vec {
 	return u * V(c, 0)
 }
 
-// ScaledXY returns the vector u multiplied by vector v component-wise.
+// ScaledXY returns the vector u multiplied by the vector v component-wise.
 func (u Vec) ScaledXY(v Vec) Vec {
 	return V(u.X()*v.X(), u.Y()*v.Y())
 }
@@ -116,6 +116,9 @@ func (u Vec) Cross(v Vec) float64 {
 
 // Map applies the function f to both x and y components of the vector u and returns the modified
 // vector.
+//
+//   u := pixel.V(10.5, -1.5)
+//   v := u.Map(math.Floor)   // v is Vec(10, -2), both components of u floored
 func (u Vec) Map(f func(float64) float64) Vec {
 	return V(
 		f(u.X()),
@@ -125,7 +128,7 @@ func (u Vec) Map(f func(float64) float64) Vec {
 
 // Lerp returns a linear interpolation between vectors a and b.
 //
-// This function basically returns a point along the line between a and b and t chooses which point.
+// This function basically returns a point along the line between a and b and t chooses which one.
 // If t is 0, then a will be returned, if t is 1, b will be returned. Anything between 0 and 1 will
 // return the appropriate point between a and b and so on.
 func Lerp(a, b Vec, t float64) Vec {
@@ -163,7 +166,7 @@ func (r Rect) Norm() Rect {
 	}
 }
 
-// String returns the string representation of the rectangle.
+// String returns the string representation of the Rect.
 //
 //   r := pixel.R(100, 50, 200, 300)
 //   r.String()     // returns "Rect(100, 50, 200, 300)"
@@ -172,22 +175,22 @@ func (r Rect) String() string {
 	return fmt.Sprintf("Rect(%v, %v, %v, %v)", r.Min.X(), r.Min.Y(), r.Max.X(), r.Max.Y())
 }
 
-// W returns the width of the rectangle.
+// W returns the width of the Rect.
 func (r Rect) W() float64 {
 	return r.Max.X() - r.Min.X()
 }
 
-// H returns the height of the rectangle.
+// H returns the height of the Rect.
 func (r Rect) H() float64 {
 	return r.Max.Y() - r.Min.Y()
 }
 
-// Size returns the vector of width and height as components respectively.
+// Size returns the vector of width and height of the Rect.
 func (r Rect) Size() Vec {
 	return V(r.W(), r.H())
 }
 
-// Center returns the position of the center of the rectangle.
+// Center returns the position of the center of the Rect.
 func (r Rect) Center() Vec {
 	return (r.Min + r.Max) / 2
 }
@@ -200,14 +203,15 @@ func (r Rect) Moved(delta Vec) Rect {
 	}
 }
 
-// Resized returns the Rect resized to the given size while keeping the position of the given anchor.
+// Resized returns the Rect resized to the given size while keeping the position of the given
+// anchor.
 //
 //   r.Resized(r.Min, size)      // resizes while keeping the position of the lower-left corner
 //   r.Resized(r.Max, size)      // same with the top-right corner
 //   r.Resized(r.Center(), size) // resizes around the center
 //
-// This function does not make sense for size of zero area and will panic. Use ResizeMin in the case
-// of zero area.
+// This function does not make sense for sizes of zero area and will panic. Use ResizedMin in the
+// case of zero area.
 func (r Rect) Resized(anchor, size Vec) Rect {
 	if r.W()*r.H() == 0 || size.X()*size.Y() == 0 {
 		panic(fmt.Errorf("(%T).Resize: zero area", r))

interface.go

@@ -5,7 +5,8 @@ import "image/color"
 // Target is something that can be drawn onto, such as a window, a canvas, and so on.
 //
 // You can notice, that there are no "drawing" methods in a Target. That's because all drawing
-// happens indirectly through Triangles instance generated via MakeTriangles method.
+// happens indirectly through Triangles and Picture instances generated via MakeTriangles and
+// MakePicture method.
 type Target interface {
 	// MakeTriangles generates a specialized copy of the provided Triangles.
 	//
@@ -63,7 +64,7 @@ type Triangles interface {
 	// Properies not supported by these Triangles should be ignored. Properties not supported by
 	// the supplied Triangles should be left untouched.
 	//
-	// The two Triangles need to have the same Len.
+	// The two Triangles must have the same Len.
 	Update(Triangles)
 
 	// Copy creates an exact independent copy of this Triangles (with the same underlying type).
@@ -93,7 +94,9 @@ type TrianglesColor interface {
 
 // TrianglesPicture specifies Triangles with Picture propery.
 //
-// Note that this represents picture coordinates, not an actual picture.
+// The first value returned from Picture method is Picture coordinates. The second one specifies the
+// weight of the Picture. Value of 0 means, that Picture should be completely ignored, 1 means that
+// is should be fully included and anything in between means anything in between.
 type TrianglesPicture interface {
 	Triangles
 	Picture(i int) (pic Vec, intensity float64)
@@ -108,7 +111,7 @@ type Picture interface {
 
 	// Slice returns a sub-Picture with specified Bounds.
 	//
-	// A result Slice-ing outside the original Bounds is unspecified.
+	// A result of Slice-ing outside the original Bounds is unspecified.
 	Slice(Rect) Picture
 
 	// Original returns the most original Picture (may be itself) that this Picture was created