Documentation refinements

Readme.md

@@ -1,4 +1,4 @@
-# Pingo - a simple ping visualizer written in go
+# Pingo - a simple ping visualizer written in go using the bubbletea framework
 
 To run the project, simply `go run cmd/pingo.go`
 
@@ -25,13 +25,16 @@ bubble := pingo.InitialPeakModel()
  - [ ] "scroll peek" refinements
 
 ## Core
+
  - [x] Implements Bubbletea framework
  - [x] Implements lipgloss styling
  - [x] Implements viewport logic via bubbles
  - [x] Implements ntcharts framework for tables
 
 ## Extras
+
  - [ ] Implement ssh TUI client (via wish)
+ - [ ] Implement peak and average models (currently implemented: peak)
 
 ## resources
 

cmd/pingo.go

@@ -1,4 +1,29 @@
 // A simple TUI application that charts latency times to specified hosts.
+//
+// The TUI uses the bubbletea framework for its lifecycle and the lipgloss
+// framework for stylized text rendering, for more on these concepts, see their
+// respective documentation.
+//
+// The bubbletea Model consists of a scroll aware container for the pingo.Peak
+// bubble, the minimum polling rate to enforce, and a pingo.Peak instance.
+//
+// The Model.Update function simply interprets ctrl+c signals as quit commands,
+// updates viewport/bubble sizes, and runs the viewport and pingo.Peak update
+// functions.
+//
+// The Model.View function prepends and appends a title and footer to the
+// viewport, as derived by Model.header() and Model.footer()
+//
+// The main function first captures the following arguments from the user:
+//
+//	-s [as time.Duration]: the polling interval
+//	-h [as int]: the desired chart height
+//	addresses [as []string]: the addresses to poll.
+//
+// The main function will exit 1 if any of these arguments fail to validate.
+//
+// Finally, the main function executes bubbletea.Model.Run, exiting 1 upon any
+// errors.
 package main
 
 import (

issues/roadmap:-docs-update/description

@@ -1 +0,0 @@
-Provide a fully featured documentation overview in source

ping.go

@@ -1,5 +1,3 @@
-// TODO(performance): implement ping message channel buffering
-//
 // Pingo defines a number of high level functions and data structures to
 // interact with and represent a Ping via Go. Primarily, it defines the
 // Ping() function and Address data structure.
@@ -34,12 +32,16 @@
 //		...
 //		a := Address{Address:"google.ca", MaxResults:20}
 //		latency, err := a.Ping() 	// get a single result and return the value
-//		... 											// handle error
-//		a.Results, err = a.Poll()	// append a ping to the Results slice, then return the updated slice
-//		... 											// handle error
-//		a.Results = a.Truncate()	// return a modified slice of only the most n*a.MaxResults long
+//		...
+//		// append a ping to the Results slice, then return the updated slice
+//		a.Results, err = a.Poll()
+//		...
+//		// return a modified slice of only the most n*a.MaxResults long
+//		a.Results = a.Truncate()
 //
 // For more, see each function's GoDoc.
+//
+// TODO(performance): implement ping message channel buffering
 package pingo
 
 import (
@@ -106,14 +108,14 @@ type Address struct {
 	MaxResults int
 }
 
-// Enforces a Address.Result maximum length by dropping the oldest result,
+// Enforces an Address.Result maximum length by dropping the oldest results,
 // then returns the modified slice.
 func (a Address) Truncate() []float64 {
 	if len(a.Results) > a.MaxResults {
-		a.Results = a.Results[len(a.Results)-a.MaxResults : len(a.Results)] // return modified slice missing first index
+		a.Results = a.Results[len(a.Results)-a.MaxResults : len(a.Results)]
 	}
 
-	return a.Results
+	return a.Results // return modified slice less oldest results
 }
 
 // Wraps Ping, passing Address.Address as its argument.

tui.go

@@ -1,7 +1,3 @@
-// TODO(chart): dynamically render charts to fit height on not set
-//
-// TODO(styling): allow end user to define their own styles when hacking.
-//
 // Pingo defines an extensible TUI based on the bubbletea framework (v2). An
 // executable entry point is defined via cmd/pingo.go. For more on this topic,
 // see the Readme.
@@ -18,7 +14,9 @@
 //   - addresses([]string): the hosts to ping. The length must be greater than
 //     or equal to 1
 //
-//   - speed(time.Duration): the polling interval
+//   - width(int): the width of the bubble
+//
+//   - height(int): the height of the bubble
 //
 //   - chartHeight(int): the desired height of the resulting charts. This
 //     argument is integral to ensuring desired rendering of charts, when
@@ -28,11 +26,14 @@
 //
 //     NOTE: chartHeight is ignored when only one address or host is provided
 //
+//     NOTE: if a specific chartHeight is specified, it is possible to exceeed
+//     desired height.
+//
 // For more, please please see InitialPeakBubble()
 //
 // Pingo defines the following bubbletea.Cmd functions:
 //
-//   - Model.Poll() tea.Msg: used to asynchronously call all Model.Addresses.Poll()
+//   - Peak.Poll() tea.Msg: used to asynchronously call all Model.Addresses.Poll()
 //     functions.
 //
 // NOTE: the project does not implement a timing mechanism for polling Addresses.
@@ -43,7 +44,16 @@
 // As timing may be handled in a number of ways, it exceeds the scope of this
 // project to provide one.
 //
-// For an example implementation, see cmd/pingo.go
+// For an example implementation, including a recommended timing mechanisim,
+// see cmd/pingo.go.
+//
+// TODO(chart): dynamically render charts to fit height on not set
+//
+// TODO(styling): allow end user to define their own styles when hacking.
+//
+// TODO(deprecate chart height): in future, specifying chart height's directly
+// will be deprecated in favour of a dynamically determined chart height. (see
+// "TODO(chart)")
 package pingo
 
 import (
@@ -107,7 +117,7 @@ type ( // tea.Msg signatures
 // Bubbletea bubble
 type Peak struct {
 	Addresses   []Address // as defined in internal/tui/types.go
-	ChartHeight int
+	ChartHeight int       // DEPRECATE
 	Height      int
 	Width       int
 }
@@ -181,7 +191,7 @@ func (p Peak) View() tea.View {
 				// render chart at fullscreen minus a few lines to hint at scrolling
 				slc = streamlinechart.New(p.Width, p.Height-2)
 			} else {
-				slc = streamlinechart.New(p.Width, p.ChartHeight-1)
+				slc = streamlinechart.New(p.Width, p.ChartHeight-1) // DEPRECATE
 			}
 
 			for _, v := range address.Results {