searchbar.go docs; references #6

Signed-off-by: Mario Kozjak <[email protected]>

internal/bar/searchbar.go

@@ -10,16 +10,33 @@ import (
 	"github.com/mkozjak/tview"
 )
 
+// A SearchBar is a [Bar] component that provides fuzzy search capability for artists.
+// It is shown on Bar when called via the forward-slash keyboard key by default.
 type SearchBar struct {
+	// The following fields hold interfaces that are used for communicating with
+	// [Bar] and library instances.
 	switcher  switcher
 	library   library.Command
+
+	// A tview-specific widget that provides query input to the user in order
+	// to initiate an artist fuzzy search feature.
 	container *tview.InputField
 }
 
+// newSearchBar returns a new [SearchBar] given its dependencies switcher and library instances
+// SearchBar is then used for the creation of a container, tview.InputField, that is
+// directly used by the app to focus the search input field.
 func newSearchBar(s switcher, l library.Command) *SearchBar {
 	return &SearchBar{switcher: s, library: l}
 }
 
+// createContainer creates a [SearchBar] container returning a pointer to
+// tview's InputField type, that is directly used by app in order to turn on
+// the search bar on [Bar] to start user's query.
+//
+// Input is automatically prefixed with the string "search: " followed by
+// user's input. The user can either confirm their query pressing the Enter key
+// or cancel input by pressing the Escape key on the keyboard.
 func (s *SearchBar) createContainer() *tview.InputField {
 	s.container = tview.NewInputField().
 		SetLabel("search: ").
@@ -36,6 +53,17 @@ func (s *SearchBar) createContainer() *tview.InputField {
 	return s.container
 }
 
+// done is a callback method that gets called after the user confirms their
+// search query pressing on of the Enter or Escape keys on the keyboard.
+// In case when Enter is pressed, the program fetches user's input and also
+// prepares tokens that are generated by splitting currently iterated artist name by
+// whitespace (" "). These tokens, along with the query, are then each sent as
+// input to [internal.JWSimilarity], that is the Jaro-Winkler Distance metric implementation.
+// A result that has a better JW score is then chosen for that artist.
+// A method then calls [library.FilterArtistPane] that redraws Artist Pane with
+// search results, or matched artists.
+//
+// This method is used by tview.InputField.SetDoneFunc method in [createContainer].
 func (s *SearchBar) done(key tcell.Key) {
 	switch key {
 	case tcell.KeyEnter: