Comments updated. (#31)

Updated doc strings.

Author: proway2

calc/shval3.go

@@ -2,10 +2,15 @@ package calc
 
 import "math"
 
-// Calculates field components from spherical harmonic (sh) models.
-// x - northward component
-// y - eastward component
-// z - vertically-downward component
+// Computes field components from spherical harmonic (sh) models.
+// The calculation is performed for two sets of coeffs for a single location,
+// thus it returns two sets of X, Y, Z.
+//
+// X - northward component
+//
+// Y - eastward component
+//
+// Z - vertically-downward component
 func Shval3(flat, flon, elev float64, nmax int, gha, ghb *[]float64) (float64, float64, float64, float64, float64, float64) {
 	// similar to shval3 from C implementation
 	var earths_radius float64 = 6371.2
@@ -150,10 +155,14 @@ func Shval3(flat, flon, elev float64, nmax int, gha, ghb *[]float64) (float64, f
 	return x, y, z, xtemp, ytemp, ztemp
 }
 
-// Computes the geomagnetic d, i, h, and f from x, y, and z.
+// Computes the geomagnetic D, I, H, and F from X, Y, and Z.
+//
 // D  - declination
+//
 // I  - inclination
+//
 // H  - horizontal intensity
+//
 // F  - total intensity
 func Dihf(x, y, z float64) (float64, float64, float64, float64) {
 	var d, i, h, f float64

coeffs/read.go

@@ -33,7 +33,7 @@ type epochData struct {
 	coeffs *[]float64
 }
 
-// NewCoeffsData - returns an initialized IGRF SHC data structure.
+// Returns an initialized IGRF SHC data structure.
 func NewCoeffsData() (*IGRFcoeffs, error) {
 	igrf := IGRFcoeffs{data: &map[string]*epochData{}}
 	if err := igrf.readCoeffs(); err != nil {
@@ -42,7 +42,8 @@ func NewCoeffsData() (*IGRFcoeffs, error) {
 	return &igrf, nil
 }
 
-// Coeffs - returns two sets of SHC coeffs for the given `date`, as well as for `date` plus one year. Also returns the maximal spherical harmonic degree.
+// Returns two sets of SH coeffs for the given `date`,
+// as well as for `date` plus one year. Also returns the maximal spherical harmonic degree.
 func (igrf *IGRFcoeffs) Coeffs(date float64) (*[]float64, *[]float64, int, error) {
 	max_column := len(*igrf.epochs)
 	min_epoch := (*igrf.epochs)[0]
@@ -65,6 +66,10 @@ func (igrf *IGRFcoeffs) Coeffs(date float64) (*[]float64, *[]float64, int, error
 	return coeffs_start, coeffs_end, nmax, nil
 }
 
+// Computes a set of SH coeffs and the maximal spherical harmonic degree
+// for a given `date` and `start_epoch`, `end_epoch`.
+//
+// `date` must be less than the maximal possible epoch.
 func (igrf *IGRFcoeffs) interpolateCoeffs(start_epoch, end_epoch string, date float64) (*[]float64, int) {
 	factor, err := findDateFactor(start_epoch, end_epoch, date)
 	if err != nil {
@@ -116,6 +121,10 @@ func (igrf *IGRFcoeffs) interpolateCoeffs(start_epoch, end_epoch string, date fl
 	return &values, nmax
 }
 
+// Computes a set of SH coeffs and the maximal spherical harmonic degree
+// for a given `date` and `start_epoch`, `end_epoch`.
+//
+// `date` is beyond than the maximal possible epoch.
 func (igrf *IGRFcoeffs) extrapolateCoeffs(start_epoch, end_epoch string, date float64) *[]float64 {
 	dte1, _ := strconv.ParseFloat(start_epoch, 32)
 	factor := date - dte1
@@ -145,6 +154,8 @@ func (igrf *IGRFcoeffs) extrapolateCoeffs(start_epoch, end_epoch string, date fl
 	return &values
 }
 
+// Calculates start and end epochs for a given date,
+// default `interval` is used for borders and for multiplicity
 func (igrf *IGRFcoeffs) findEpochs(date float64) (string, string) {
 	max_column := len(*igrf.epochs)
 	min_epoch := (*igrf.epochs)[0]
@@ -162,6 +173,7 @@ func (igrf *IGRFcoeffs) findEpochs(date float64) (string, string) {
 	return start_epoch, end_epoch
 }
 
+// The main function that populates the existing `IGRFcoeffs` structure.
 func (igrf *IGRFcoeffs) readCoeffs() error {
 	line_provider := coeffsLineProvider()
 
@@ -189,6 +201,7 @@ func (igrf *IGRFcoeffs) readCoeffs() error {
 	return nil
 }
 
+// Finds lines with epochs, parses these lines and returns arrays of epochs: names and floats.
 func getEpochs(reader <-chan string) (*[]string, *[]float64, error) {
 	cs_re := regexp.MustCompile(`^c/s.*`)
 	for line := range reader {
@@ -202,6 +215,7 @@ func getEpochs(reader <-chan string) (*[]string, *[]float64, error) {
 	return nil, nil, errors.New("Unable to get epochs.")
 }
 
+// Parses the header of the coeffs. Usually it's the first two non-comment lines.
 func parseHeader(line1, line2 string) ([]string, []float64) {
 	line1_data := space_re.Split(line1, -1)
 	line2_data := space_re.Split(line2, -1)
@@ -236,6 +250,7 @@ func parseHeader(line1, line2 string) ([]string, []float64) {
 	return names, epochs[shift:]
 }
 
+// Parses lines with coefficients and populates the `IGRFcoeffs` structure.
 func (igrf *IGRFcoeffs) getCoeffsForEpochs(provider <-chan string) error {
 	var i int = 0
 	for line := range provider {
@@ -250,6 +265,7 @@ func (igrf *IGRFcoeffs) getCoeffsForEpochs(provider <-chan string) error {
 	return nil
 }
 
+// Populates the corresponding fields inside the `IGRFcoeffs` structure with actual coeffs.
 func (igrf *IGRFcoeffs) loadCoeffs(line_num int, line_coeffs *[]float64) {
 	for index, coeff := range *line_coeffs {
 		epoch := (*igrf.epochs)[index]
@@ -258,7 +274,7 @@ func (igrf *IGRFcoeffs) loadCoeffs(line_num int, line_coeffs *[]float64) {
 	}
 }
 
-// nMaxForEpoch - returns max spherical harmonic degree for a certain epoch
+// Returns max spherical harmonic degree for a certain epoch.
 func nMaxForEpoch(epoch string) (int, error) {
 	// this is hardcoded
 	var nmax int

coeffs/utils.go

@@ -68,7 +68,7 @@ func findDateFactor(start_epoch, end_epoch string, date float64) (float64, error
 	return factor, nil
 }
 
-// coeffsLineProvider - reads lines from raw coeffs data, omits comments
+// Reads lines from raw coeffs data and writes a srting into a channel, drops comments.
 func coeffsLineProvider() <-chan string {
 	ch := make(chan string)
 	coeffs_reader := strings.NewReader(igrf13coeffs)
@@ -92,6 +92,7 @@ func epoch2string(epoch float64) string {
 	return fmt.Sprintf("%.1f", epoch)
 }
 
+// Parses an array of strings into an array of floats.
 func parseArrayToFloat(raw_data []string) (*[]float64, error) {
 	data := make([]float64, len(raw_data))
 	for index, token := range raw_data {

igrf/igrf.go

@@ -10,10 +10,14 @@ import (
 	"github.com/proway2/go-igrf/coeffs"
 )
 
-// IGRF computes values for the geomagnetic field and secular variation for a given set of coordinates and date.
+// IGRF computes values for the geomagnetic field and secular variation for a given set of coordinates and date
+// and returns a populated `IGRFresults` structure.
+//
 // lat, lon - geodetic latitude and longitude (WGS84 latitude and altitude above mean sea level).
 // Valid values -90.0 < lat < 90.0, -180.0 < lon < 180.0.
+//
 // alt - geodetic altitude above mean sea level in km (-1.00 to 600.00).
+//
 // date - decimal date (1900.00 to 2025).
 func IGRF(lat, lon, alt, date float64) (IGRFresults, error) {
 	if err := checkInitialConditions(lat, lon, alt); err != nil {

igrf/result.go

@@ -3,19 +3,33 @@ package igrf
 // IGRFresults represents the result of IGRF calculation
 //
 // Fields:
+//
 // Declination (D):  14.175 ° (+ve east)
+//
 // DeclinationSV (D): -8.92 arcmin/yr
+//
 // Inclination (I):  74.229 ° (+ve down)
+//
 // InclinationSV (I): -2.59 arcmin/yr
+//
 // HzIntensity (Horizontal intensity (H)):  14626.6 nT
+//
 // HorizontalSV (H):  -16.8 nT/yr
+//
 // NorthComponent (X):  14181.2 nT
+//
 // NorthSV (X): -28.2 nT/yr
+//
 // EastComponent (Y):  3581.8 nT
+//
 // EastSV (Y):  32.0 nT/yr
+//
 // VerticalComponent (Z):  51788.4 nT
+//
 // VerticalSV (Z):  80.1 nT/yr
+//
 // TotalIntensity (F):  53814.3 nT
+//
 // TotalSV (F):  71.8 nT/yr
 type IGRFresults struct {
 	Declination         float64