Improved element documentation

elements/basic/doc.go

@@ -0,0 +1,3 @@
+// Package basicElements provides standard elements that are commonly used in
+// GUI applications.
+package basicElements

elements/core/doc.go

@@ -0,0 +1,7 @@
+// Package core provides tools that allow elements to easily fulfill common
+// interfaces without having to duplicate a ton of code. Each "core" is a type
+// that can be embedded into an element directly, working to fulfill a
+// particular interface. Each one comes with a corresponding core control, which
+// provides an interface for elements to exert control over the core. They
+// should be kept private.
+package core

elements/doc.go

@@ -0,0 +1,6 @@
+// Package elements provides several standard interfaces that elements can
+// fulfill in order to inform other elements of their capabilities and what
+// events they are able to process. Sub-packages of this package provide
+// pre-made standard elements, as well as tools that can be used to easily
+// create more.
+package elements

elements/element.go

@@ -60,7 +60,9 @@ type Focusable interface {
 
 	// OnFocusRequest sets a function to be called when this element wants
 	// its parent element to focus it. Parent elements should return true if
-	// the request was granted, and false if it was not.
+	// the request was granted, and false if it was not. If the parent
+	// element returns true, the element must act as if a HandleFocus call
+	// was made with KeynavDirectionNeutral.
 	OnFocusRequest (func () (granted bool))
 
 	// OnFocusMotionRequest sets a function to be called when this

elements/fun/doc.go

@@ -0,0 +1,3 @@
+// Package fun provides "fun" elements that have few actual use cases, but serve
+// as good demos of what Tomo is capable of.
+package fun

elements/fun/piano.go

@@ -15,6 +15,7 @@ type pianoKey struct {
 	music.Note
 }
 
+// Piano is an element that can be used to input midi notes.
 type Piano struct {
 	*core.Core
 	core core.CoreControl
@@ -32,7 +33,15 @@ type Piano struct {
 	onRelease func (music.Note)
 }
 
+// NewPiano returns a new piano element with a lowest and highest octave,
+// inclusive. If low is greater than high, they will be swapped.
 func NewPiano (low, high music.Octave) (element *Piano) {
+	if low > high {
+		temp := low
+		low = high
+		high = temp
+	}
+	
 	element = &Piano {
 		low:  low,
 		high: high,

elements/testing/doc.go

@@ -0,0 +1,3 @@
+// Package testing provides elements that are used to test different parts of
+// Tomo's API.
+package testing