docs: Add docs

Signed-off-by: Tim Hårek Andreassen <tim@harek.no>

main.go

@@ -2,6 +2,7 @@ package main
 
 import "git.sr.ht/~timharek/yr/cmd"
 
+// Execute CLI
 func main() {
 	cmd.Execute()
 }

pkg/cache/cache.go

@@ -14,6 +14,7 @@ type Cache[T any] struct {
 	Path string
 }
 
+// New Cache where default path is os.TempDir()
 func New[T any](path string) *Cache[T] {
 	if path == "" {
 		path = os.TempDir()

pkg/met/met.go

@@ -1,3 +1,4 @@
+// Access [Meteorologisk institutt's API](https://api.met.no)
 package met
 
 import (
@@ -12,6 +13,7 @@ type Met struct {
 	siteName string
 }
 
+// Returns valid Met client or error if empty siteName is provided
 func New(siteName string) (*Met, error) {
 	if siteName == "" {
 		return nil, fmt.Errorf("`siteName` must be defined.")
@@ -22,6 +24,8 @@ func New(siteName string) (*Met, error) {
 	}, nil
 }
 
+// Get LocationForecast from Met, returns error if Met doesn't answer or response is missing required headers
+// API endpoint: https://api.met.no/weatherapi/locationforecast/2.0/documentation
 func (m *Met) Forecast(lat, lon float64, alt *int) (*LocationForecastResult, error) {
 	url := "https://api.met.no/weatherapi/locationforecast/2.0/complete"
 

pkg/nominatim/nominatim.go

@@ -24,6 +24,8 @@ func New(siteName string) (*Nominatim, error) {
 	}, nil
 }
 
+// Search for coordinates based on q
+// API endpoint: https://nominatim.openstreetmap.org/search
 func (n *Nominatim) Search(q string) (*SearchResults, error) {
 	url := fmt.Sprintf("https://nominatim.openstreetmap.org/search?q=%s&format=jsonv2", url.QueryEscape(q))
 
@@ -58,6 +60,8 @@ func (n *Nominatim) Search(q string) (*SearchResults, error) {
 	return &result, nil
 }
 
+// Reverse search for location based on lat and lon
+// API endpoint: https://nominatim.openstreetmap.org/reverse
 func (n *Nominatim) Reverse(lat, lon float64) (*ReverseResult, error) {
 	url := fmt.Sprintf("https://nominatim.openstreetmap.org/reverse?lat=%.16f&lon=%.16f&format=jsonv2", lat, lon)
 
@@ -101,6 +105,7 @@ type LookupResult struct {
 	Location string `json:"location"`
 }
 
+// Lookup location coordinates based on q
 func (n *Nominatim) Lookup(q string) (*LookupResult, error) {
 	r, err := n.Search(q)
 
@@ -132,6 +137,7 @@ func (n *Nominatim) Lookup(q string) (*LookupResult, error) {
 	}, nil
 }
 
+// Lookup location name based on lat and lon
 func (n *Nominatim) ReverseLookup(lat, lon float64) (*LookupResult, error) {
 	r, err := n.Reverse(lat, lon)
 
@@ -148,6 +154,7 @@ func (n *Nominatim) ReverseLookup(lat, lon float64) (*LookupResult, error) {
 	}, nil
 }
 
+// Check if all fields on s is nil
 func allFieldsNil(s interface{}) bool {
 	v := reflect.ValueOf(s)
 

yr/direction/direction.go

@@ -1,12 +1,13 @@
 package direction
 
+// Cardinal direction in unicode arrow
 const (
-	NORTH      = "↑"
-	SOUTH      = "↓"
-	WEST       = "←"
-	EAST       = "→"
-	NORTH_WEST = "↖"
-	NORTH_EAST = "↗"
-	SOUTH_WEST = "↙"
-	SOUTH_EAST = "↘"
+	NORTH      string = "↑"
+	SOUTH      string = "↓"
+	WEST       string = "←"
+	EAST       string = "→"
+	NORTH_WEST string = "↖"
+	NORTH_EAST string = "↗"
+	SOUTH_WEST string = "↙"
+	SOUTH_EAST string = "↘"
 )

yr/yr.go

@@ -18,6 +18,7 @@ type Client struct {
 	cache cache.Cache[ForecastResult]
 }
 
+// New default Yr client
 func New() (*Client, error) {
 	siteName := "git.sr.ht/~timharek/yr"
 	met, err := met.New(siteName)
@@ -38,6 +39,7 @@ type wind struct {
 	Direction float64 `json:"direction"`
 }
 
+// Returns wind direction to an unicode arrow
 func (w *wind) DirectionToString() string {
 	return windDirection(w.Direction)
 }
@@ -68,6 +70,7 @@ func windDirection(d float64) string {
 	}
 }
 
+// A forecast
 type Forecast struct {
 	nominatim.LookupResult
 	Time          time.Time `json:"time"`
@@ -76,6 +79,7 @@ type Forecast struct {
 	Wind          wind      `json:"wind"`          // In m/s
 }
 
+// A forecast result with metadata
 type ForecastResult struct {
 	Expires      time.Time             `json:"expires"`
 	LastModified time.Time             `json:"lastModified"`
@@ -83,6 +87,7 @@ type ForecastResult struct {
 	Forecast     []Forecast            `json:"forecast"`
 }
 
+// Current forecast for q
 func (c *Client) Now(q string) (*ForecastResult, error) {
 	cacheResult, err := c.cache.Get(q)
 	if err != nil {
@@ -103,6 +108,7 @@ func (c *Client) Now(q string) (*ForecastResult, error) {
 	}, &coords.Location)
 }
 
+// Current forecast for coords
 func (c *Client) NowCoords(coords *nominatim.Coordinates, location *string) (*ForecastResult, error) {
 	result, err := c.ForecastCoords(coords, location)
 	if err != nil {
@@ -114,6 +120,7 @@ func (c *Client) NowCoords(coords *nominatim.Coordinates, location *string) (*Fo
 	return result, nil
 }
 
+// Forecast for q
 func (c *Client) Forecast(q string) (*ForecastResult, error) {
 	cacheResult, err := c.cache.Get(q)
 	if err != nil {
@@ -134,6 +141,7 @@ func (c *Client) Forecast(q string) (*ForecastResult, error) {
 	}, &coords.Location)
 }
 
+// Forecast for coords
 func (c *Client) ForecastCoords(coords *nominatim.Coordinates, location *string) (*ForecastResult, error) {
 	coordCacheName := fmt.Sprintf("%.4f_%.4f", coords.Latitude, coords.Longitude)
 	cacheResult, err := c.cache.Get(coordCacheName)
@@ -224,6 +232,7 @@ func (c *Client) ForecastCoords(coords *nominatim.Coordinates, location *string)
 	return &result, nil
 }
 
+// Helper to sort met.Timeseries
 func sortTimeSeries(a, b met.Timeseries) int {
 	return cmp.Compare(a.Time.Unix(), b.Time.Unix())
 }