From 2cd670f4cd4775f64380611783d2bfba27ed9065 Mon Sep 17 00:00:00 2001
From: Sasha Koshka <supergriffin64@gmail.com>
Date: Thu, 9 Feb 2023 14:50:24 -0500
Subject: [PATCH] Improved element documentation

---
 elements/basic/doc.go   | 3 +++
 elements/core/doc.go    | 7 +++++++
 elements/doc.go         | 6 ++++++
 elements/element.go     | 4 +++-
 elements/fun/doc.go     | 3 +++
 elements/fun/piano.go   | 9 +++++++++
 elements/testing/doc.go | 3 +++
 7 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 elements/basic/doc.go
 create mode 100644 elements/core/doc.go
 create mode 100644 elements/doc.go
 create mode 100644 elements/fun/doc.go
 create mode 100644 elements/testing/doc.go

diff --git a/elements/basic/doc.go b/elements/basic/doc.go
new file mode 100644
index 0000000..bc5c32c
--- /dev/null
+++ b/elements/basic/doc.go
@@ -0,0 +1,3 @@
+// Package basicElements provides standard elements that are commonly used in
+// GUI applications.
+package basicElements
diff --git a/elements/core/doc.go b/elements/core/doc.go
new file mode 100644
index 0000000..09bdd65
--- /dev/null
+++ b/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
diff --git a/elements/doc.go b/elements/doc.go
new file mode 100644
index 0000000..e8e2fbd
--- /dev/null
+++ b/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
diff --git a/elements/element.go b/elements/element.go
index 8aaa63f..57d436b 100644
--- a/elements/element.go
+++ b/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
diff --git a/elements/fun/doc.go b/elements/fun/doc.go
new file mode 100644
index 0000000..e53afa3
--- /dev/null
+++ b/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
diff --git a/elements/fun/piano.go b/elements/fun/piano.go
index 64a0177..c9356e0 100644
--- a/elements/fun/piano.go
+++ b/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,
diff --git a/elements/testing/doc.go b/elements/testing/doc.go
new file mode 100644
index 0000000..20eca0c
--- /dev/null
+++ b/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