Improve some doc comments

internal/system/hierarchy.go

@@ -31,12 +31,19 @@ type Hierarchy struct {
 	minimumClean bool
 }
 
-// WindowLink allows the Hierarchy to call up into the backend implementation
-// which contains it.
+// WindowLink allows the Hierarchy to call up into the tomo.Window
+// implementation which contains it. This should be a separate entity from the
+// tomo.Window.
 type WindowLink interface {
-	GetWindow               () tomo.Window
-	PushRegion              (image.Rectangle)
-	PushAll                 ()
+	// GetWindow returns the tomo.Window containing the Hierarchy.
+	GetWindow () tomo.Window
+	// PushRegion pushes a region of the held canvas.Canvas to the screen.
+	PushRegion (image.Rectangle)
+	// PushAll pushes the entire canvas.Canvas to the screen.
+	PushAll ()
+	// NotifyMinimumSizeChange notifies the tomo.Window that the minimum
+	// size of the Hierarchy has changed, and if necessary, a resize should
+	// be requested.
 	NotifyMinimumSizeChange ()
 }
 
@@ -67,7 +74,7 @@ func (this *Hierarchy) SetRoot (root tomo.Box) {
 }
 
 // SetCanvas sets the held canvas of the Hierarchy that all boxes within it will
-// draw to. The Hierarchy will take on the canvas's bounds to lay itself out.
+// draw to. The Hierarchy will use the canvas.Canvas's bounds to lay itself out.
 func (this *Hierarchy) SetCanvas (can canvas.Canvas) {
 	this.canvas = can
 	if this.root != nil { this.root.loseCanvas() }

internal/system/surfacebox.go

@@ -3,6 +3,11 @@ package system
 import "errors"
 import "git.tebibyte.media/tomo/tomo"
 
+// TODO before implementing this, tomo.SurfaceBox needs a Close behavior. That
+// way, we know when to close the surface itself. Additionally, we need some
+// kind of OnReallocate method that is called when the surface is re-allocated
+// due to a resize or something.
+
 func (this *System) NewSurfaceBox () (tomo.SurfaceBox, error) {
 	// TODO
 	return nil, errors.New("system: not implemented yet")

internal/system/system.go

@@ -9,11 +9,14 @@ type System struct {
 	link BackendLink
 }
 
-// BackendLink allows the System to call up into the backend implementation
+// BackendLink allows the System to call up into the tomo.Backend implementation
 // which contains it in order to do things such as create new textures.
 type BackendLink interface {
+	// NewTexture creates a new texture from an image.
 	NewTexture (image.Image) canvas.TextureCloser
+	// NewCanvas creates a new blank canvas with the specified bounds.
 	NewCanvas  (image.Rectangle) canvas.Canvas
+	// NewSurface creates a new surface with the specified bounds.
 	NewSurface (image.Rectangle) SurfaceLink
 }