Add doc comments to Forecast and associated types

types.go

@@ -7,58 +7,130 @@ import (
 	"go.elara.ws/taf/units"
 )
 
+// Forecast represents a Terminal Aerodrome Forecast (TAF) weather report for a specific airport.
 type Forecast struct {
-	Identifier    string           `json:"identifier,omitempty"`
+	// Identifier holds the ICAO airport identifier for which this forecast was issued.
-	Airport       airports.Airport `json:"airport,omitempty"`
+	Identifier string `json:"identifier,omitempty"`
-	PublishTime   time.Time        `json:"publish_time,omitempty"`
+
-	Valid         ValidPair        `json:"valid,omitempty"`
+	// Airport provides additional information about the airport for which this forecast was issued.
-	Visibility    Visibility       `json:"visibility,omitempty"`
+	Airport airports.Airport `json:"airport,omitempty"`
-	Wind          Wind             `json:"wind,omitempty"`
+
-	SkyCondition  []SkyCondition   `json:"sky_condition,omitempty"`
+	// PublishTime indicates the time at which this forecast was issued.
-	Temperature   []Temperature    `json:"temperature,omitempty"`
+	PublishTime time.Time `json:"publish_time,omitempty"`
-	Weather       []Weather        `json:"weather,omitempty"`
+
-	Probabilities []*Probability   `json:"probabilities,omitempty"`
+	// Valid defines the period during which this forecast is applicable.
-	Changes       []*Change        `json:"changes,omitempty"`
+	Valid ValidPair `json:"valid,omitempty"`
-	Flags         []Flag           `json:"flags,omitempty"`
+
+	// Visibility describes the anticipated visibility conditions.
+	Visibility Visibility `json:"visibility,omitempty"`
+
+	// Wind describes the projected wind conditions.
+	Wind Wind `json:"wind,omitempty"`
+
+	// SkyCondition lists the expected sky conditions.
+	SkyCondition []SkyCondition `json:"sky_condition,omitempty"`
+
+	// Temperature lists the expected temperature values.
+	Temperature []Temperature `json:"temperature,omitempty"`
+
+	// Weather lists information about the expected weather conditions.
+	Weather []Weather `json:"weather,omitempty"`
+
+	// Probabilities contains the probabilities for potential conditions.
+	Probabilities []*Probability `json:"probabilities,omitempty"`
+
+	// Changes lists any expected changes in conditions.
+	Changes []*Change `json:"changes,omitempty"`
+
+	// Flags contains special flags associated with the forecast.
+	Flags []Flag `json:"flags,omitempty"`
 }
 
+// Change represents a change in weather conditions within a forecast.
 type Change struct {
-	Type         ChangeType     `json:"type,omitempty"`
+	// Type specifies the nature of this weather change.
-	Valid        ValidPair      `json:"valid,omitempty"`
+	Type ChangeType `json:"type,omitempty"`
-	Visibility   Visibility     `json:"visibility,omitempty"`
+
-	Wind         Wind           `json:"wind,omitempty"`
+	// Valid defines the period during which this change is applicable.
+	Valid ValidPair `json:"valid,omitempty"`
+
+	// Visibility describes the anticipated visibility conditions.
+	Visibility Visibility `json:"visibility,omitempty"`
+
+	// Wind describes the projected wind conditions.
+	Wind Wind `json:"wind,omitempty"`
+
+	// SkyCondition lists the expected sky conditions.
 	SkyCondition []SkyCondition `json:"sky_condition,omitempty"`
-	Temperature  []Temperature  `json:"temperature,omitempty"`
+
-	Weather      []Weather      `json:"weather,omitempty"`
+	// Temperature lists the expected temperature values.
-	Flags        []Flag         `json:"flags,omitempty"`
+	Temperature []Temperature `json:"temperature,omitempty"`
-	Probability  int            `json:"probability,omitempty"`
+
+	// Weather lists information about the expected weather conditions.
+	Weather []Weather `json:"weather,omitempty"`
+
+	// Flags contains special flags associated with the change.
+	Flags []Flag `json:"flags,omitempty"`
+
+	// Probability indicates the percent chance of this change occurring.
+	Probability int `json:"probability,omitempty"`
 }
 
+// Probability represents the probability of potential conditions occurring within a forecast.
 type Probability struct {
-	Valid        ValidPair      `json:"valid,omitempty"`
+	// Valid defines the period during which these potential conditions are applicable.
-	Value        int            `json:"value,omitempty"`
+	Valid ValidPair `json:"valid,omitempty"`
-	Visibility   Visibility     `json:"visibility,omitempty"`
+
-	Wind         Wind           `json:"wind,omitempty"`
+	// Value indicates the percent chance of these conditions occurring.
+	Value int `json:"value,omitempty"`
+
+	// Visibility describes the anticipated visibility conditions.
+	Visibility Visibility `json:"visibility,omitempty"`
+
+	// Wind describes the projected wind conditions.
+	Wind Wind `json:"wind,omitempty"`
+
+	// SkyCondition lists the expected sky conditions.
 	SkyCondition []SkyCondition `json:"sky_condition,omitempty"`
-	Temperature  []Temperature  `json:"temperature,omitempty"`
+
-	Weather      []Weather      `json:"weather,omitempty"`
+	// Temperature lists the expected temperature values.
-	Flags        []Flag         `json:"flags,omitempty"`
+	Temperature []Temperature `json:"temperature,omitempty"`
+
+	// Weather lists information about the expected weather conditions.
+	Weather []Weather `json:"weather,omitempty"`
+
+	// Flags contains special flags associated with the potential conditions.
+	Flags []Flag `json:"flags,omitempty"`
 }
 
+// ValidPair represents a time interval for which weather data is valid.
 type ValidPair struct {
-	From     time.Time     `json:"from,omitempty"`
+	// From represents the time from which the data is valid.
-	To       time.Time     `json:"to,omitempty"`
+	From time.Time `json:"from,omitempty"`
+
+	// To indicates the time until which the data is valid.
+	To time.Time `json:"to,omitempty"`
+
+	// Duration contains the total duration for which the data remains valid
 	Duration time.Duration `json:"duration,omitempty"`
 }
 
+// Visibility represents the visibility conditions in the forecast.
 type Visibility struct {
-	Plus  bool           `json:"plus,omitempty"`
+	// Plus indicates whether visibility is expected to be greater than the specified value.
-	Value float64        `json:"value,omitempty"`
+	Plus bool `json:"plus,omitempty"`
-	Unit  units.Distance `json:"unit,omitempty"`
+
+	// Value holds the visibility measurement. Its unit is determined by the Unit field.
+	Value float64 `json:"value,omitempty"`
+
+	// Unit specifies the unit of measurement for the visibility value.
+	Unit units.Distance `json:"unit,omitempty"`
 }
 
+// SkyConditionType represents different types of sky conditions in the forecast.
 type SkyConditionType string
 
+// Sky Condition Types
 const (
 	Few                SkyConditionType = "Few"
 	Scattered          SkyConditionType = "Scattered"
@@ -68,41 +140,69 @@ const (
 	SkyClear           SkyConditionType = "SkyClear"
 )
 
+// CloudType represents different types of cloud formations.
 type CloudType string
 
+// Cloud Types
 const (
 	CumuloNimbus    CloudType = "CumuloNumbus"
 	ToweringCumulus CloudType = "ToweringCumulus"
 )
 
+// SkyCondition represents the condition of the sky, including cloud cover and altitude.
 type SkyCondition struct {
-	Type      SkyConditionType `json:"type,omitempty"`
+	// Type specifies the nature of the expected sky condition.
-	Altitude  int              `json:"altitude,omitempty"`
+	Type SkyConditionType `json:"type,omitempty"`
-	CloudType CloudType        `json:"cloud_type,omitempty"`
+
+	// Altitude represents the altitude at which this sky condition is anticipated, in feet.
+	Altitude int `json:"altitude,omitempty"`
+
+	// CloudType defines the type of clouds expected in the sky.
+	CloudType CloudType `json:"cloud_type,omitempty"`
 }
 
+// Wind represents wind-related information in a weather forecast.
 type Wind struct {
-	Direction Direction   `json:"direction,omitempty"`
+	// Direction indicates the wind direction of the expected wind.
-	WindShear int         `json:"wind_shear,omitempty"`
+	Direction Direction `json:"direction,omitempty"`
-	Speed     int         `json:"speed,omitempty"`
+
-	Gusts     int         `json:"gusts,omitempty"`
+	// WindShear specifies the altitude at which wind shear is expected.
-	Unit      units.Speed `json:"unit,omitempty"`
+	WindShear int `json:"wind_shear,omitempty"`
+
+	// Speed represents the anticipated wind speed. The unit is determined by the Unit field.
+	Speed int `json:"speed,omitempty"`
+
+	// Gusts holds the projected gust speed. The unit is determined by the Unit field.
+	Gusts int `json:"gusts,omitempty"`
+
+	// Unit denotes the unit of measurement for wind and gust speeds.
+	Unit units.Speed `json:"unit,omitempty"`
 }
 
+// Direction describes the wind direction, which can be variable.
 type Direction struct {
+	// Variable signifies if the wind direction is variable. When true, Value is set to zero.
 	Variable bool `json:"variable,omitempty"`
-	Value    int  `json:"value,omitempty"`
+
+	// Value specifies the wind direction in degrees.
+	Value int `json:"value,omitempty"`
 }
 
+// Modifier represents modifiers for weather conditions, such as "Heavy" or "Light".
 type Modifier string
 
+// Weather Modifiers
 const (
+	// Heavy indicates that weather conditions are expected to be severe.
 	Heavy Modifier = "Heavy"
+	// Light indicates that weather conditions are expected to be mild.
 	Light Modifier = "Light"
 )
 
+// Descriptor represents descriptors for weather conditions, such as "Shallow" or "Showers".
 type Descriptor string
 
+// Weather Descriptors
 const (
 	Shallow      Descriptor = "Shallow"
 	Patches      Descriptor = "Patches"
@@ -114,8 +214,10 @@ const (
 	Partial      Descriptor = "Partial"
 )
 
+// Precipitation represents different types of precipitation.
 type Precipitation string
 
+// Precipitation Types
 const (
 	Drizzle     Precipitation = "Drizzle"
 	Rain        Precipitation = "Rain"
@@ -128,8 +230,10 @@ const (
 	Unknown     Precipitation = "Unknown"
 )
 
+// Obscuration represents different types of atmospheric obscurations.
 type Obscuration string
 
+// Atmospheric Obscuration Types
 const (
 	Mist        Obscuration = "Mist"
 	Fog         Obscuration = "Fog"
@@ -141,8 +245,10 @@ const (
 	VolcanicAsh Obscuration = "VolcanicAsh"
 )
 
+// Phenomenon represents different atmospheric phenomena like whirls, squalls, etc.
 type Phenomenon string
 
+// Weather Phenomena
 const (
 	Whirls      Phenomenon = "Whirls"
 	Squalls     Phenomenon = "Squalls"
@@ -151,38 +257,67 @@ const (
 	Duststorm   Phenomenon = "Duststorm"
 )
 
+// Weather represents various weather-related conditions in the forecast.
 type Weather struct {
-	Vicinity      bool          `json:"vicinity,omitempty"`
+	// Vicinity specifies if the described weather is occurring near the airport.
-	Modifier      Modifier      `json:"modifier,omitempty"`
+	Vicinity bool `json:"vicinity,omitempty"`
-	Descriptor    Descriptor    `json:"descriptor,omitempty"`
+
+	// Modifier indicates the severity of the weather conditions.
+	Modifier Modifier `json:"modifier,omitempty"`
+
+	// Descriptor provides details about the specific type of expected weather.
+	Descriptor Descriptor `json:"descriptor,omitempty"`
+
+	// Precipitation indicates the anticipated type of precipitation.
 	Precipitation Precipitation `json:"precipitation,omitempty"`
-	Obscuration   Obscuration   `json:"obscuration,omitempty"`
+
-	Phenomenon    Phenomenon    `json:"phenomenon,omitempty"`
+	// Obscuration describes any potential atmospheric obscurations expected.
+	Obscuration Obscuration `json:"obscuration,omitempty"`
+
+	// Phenomenon contains anticipated weather phenomena.
+	Phenomenon Phenomenon `json:"phenomenon,omitempty"`
 }
 
+// TemperatureType represents different types of temperature data, like "High" or "Low".
 type TemperatureType string
 
+// Temperature Types
 const (
 	High TemperatureType = "High"
 	Low  TemperatureType = "Low"
 )
 
+// Temperature represents temperature-related details in the forecast.
 type Temperature struct {
-	Type  TemperatureType `json:"type,omitempty"`
+	// Type specifies if this temperature is a high or low value.
-	Value int             `json:"value,omitempty"`
+	Type TemperatureType `json:"type,omitempty"`
-	Time  time.Time       `json:"time,omitempty"`
+
+	// Value holds the anticipated temperature in degrees Celsius.
+	Value int `json:"value,omitempty"`
+
+	// Time indicates the expected time for this temperature.
+	Time time.Time `json:"time,omitempty"`
 }
 
+// ChangeType represents different types of changes in weather conditions.
 type ChangeType string
 
+// Change Types
 const (
-	From      ChangeType = "From"
+	// From indicates a rapid change.
-	Becoming  ChangeType = "Becoming"
+	From ChangeType = "From"
+	// Becoming indicates a slow or gradual change.
+	Becoming ChangeType = "Becoming"
+	// Temporary indicates that a change is expected to last generally less than an hour.
 	Temporary ChangeType = "Temporary"
 )
 
+// Flag represents special flags for specific weather conditions.
 type Flag string
 
+// Flags
 const (
+	// CeilingAndVisibilityOK indicates that visibility is over 10km, that
+	// there are no significant clouds, and no significant weather
 	CeilingAndVisibilityOK Flag = "CeilingAndVisibilityOK"
 )