From 97e085e2adb49e9c40fdd79c62dc526990ce21cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20H=C3=A5rek=20Andreassen?= Date: Sat, 5 Oct 2024 23:36:31 +0200 Subject: [PATCH] docs: Add docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Tim Hårek Andreassen --- main.go | 1 + pkg/cache/cache.go | 1 + pkg/met/met.go | 4 ++++ pkg/nominatim/nominatim.go | 7 +++++++ yr/direction/direction.go | 17 +++++++++-------- yr/yr.go | 9 +++++++++ 6 files changed, 31 insertions(+), 8 deletions(-) diff --git a/main.go b/main.go index 75b3d33..102fd1e 100644 --- a/main.go +++ b/main.go @@ -2,6 +2,7 @@ package main import "git.sr.ht/~timharek/yr/cmd" +// Execute CLI func main() { cmd.Execute() } diff --git a/pkg/cache/cache.go b/pkg/cache/cache.go index 0768e8c..0896ce5 100644 --- a/pkg/cache/cache.go +++ b/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() diff --git a/pkg/met/met.go b/pkg/met/met.go index 7122139..ed9076a 100644 --- a/pkg/met/met.go +++ b/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" diff --git a/pkg/nominatim/nominatim.go b/pkg/nominatim/nominatim.go index 9c0c746..8fd126c 100644 --- a/pkg/nominatim/nominatim.go +++ b/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) diff --git a/yr/direction/direction.go b/yr/direction/direction.go index ab445d7..6cee621 100644 --- a/yr/direction/direction.go +++ b/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 = "↘" ) diff --git a/yr/yr.go b/yr/yr.go index 1267bb7..e9d156d 100644 --- a/yr/yr.go +++ b/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()) }