From 8a94e5143781c62292d4cabeff07f06c4b43aa2f Mon Sep 17 00:00:00 2001
From: Fred Boniface <fred@fjla.uk>
Date: Fri, 29 Mar 2024 14:01:57 +0000
Subject: [PATCH] Add comments to describe functions and types

---
 src/background/ticker.go     | 2 ++
 src/cif/constants.go         | 3 +++
 src/cif/helpers.go           | 2 ++
 src/cif/types.go             | 1 +
 src/corpus/check.go          | 1 +
 src/corpus/fetch.go          | 3 +++
 src/corpus/stations.go       | 1 +
 src/corpus/update.go         | 1 +
 src/dbAccess/access.go       | 7 +++++++
 src/dbAccess/cif.go          | 4 ++++
 src/dbAccess/client.go       | 3 ++-
 src/dbAccess/corpus.go       | 4 ++++
 src/helpers/basicAuth.go     | 1 +
 src/helpers/config_loader.go | 2 ++
 src/helpers/vstp.go          | 1 -
 src/log/log.go               | 1 +
 src/messaging/client.go      | 1 +
 17 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/background/ticker.go b/src/background/ticker.go
index bd2d954..2eee8ac 100644
--- a/src/background/ticker.go
+++ b/src/background/ticker.go
@@ -11,10 +11,12 @@ import (
 
 const frequency = 3 * time.Second // Figure out a sensible frequency!
 
+// Starts a background ticker to run background tasks.  Uses the frequency configured in the background/ticker.go file
 func InitTicker(cfg *helpers.Configuration, stop <-chan struct{}) {
 	go runTicker(cfg, stop)
 }
 
+// Runs the ticker and handles tick events
 func runTicker(cfg *helpers.Configuration, stop <-chan struct{}) {
 	log.Msg.Sugar().Infof("Starting background ticker, runs every %s", frequency)
 	ticker := time.NewTicker(frequency)
diff --git a/src/cif/constants.go b/src/cif/constants.go
index cc43460..262b901 100644
--- a/src/cif/constants.go
+++ b/src/cif/constants.go
@@ -1,4 +1,7 @@
 package cif
 
+// The URL required for a daily update of the CIF Data - The 'day string' must be appended
 const dailyUpdateUrl = "https://publicdatafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_UPDATE_DAILY&day=toc-update-"
+
+// The URL required for a full fetch of the CIF Data
 const fullUpdateUrl = "https://publicdatafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_FULL_DAILY&day=toc-full"
diff --git a/src/cif/helpers.go b/src/cif/helpers.go
index 7109568..efe1faf 100644
--- a/src/cif/helpers.go
+++ b/src/cif/helpers.go
@@ -8,6 +8,7 @@ import (
 	"go.uber.org/zap"
 )
 
+// Fetches the day string for TODAYs update.  Needs adjusting to be able to accept a time.Time type and return the day string for that day
 func getDayString() string {
 	london, err := time.LoadLocation("Europe/London")
 	if err != nil {
@@ -22,6 +23,7 @@ func getDayString() string {
 	return dayStrings[day]
 }
 
+// Simply returns the correct URL for either a 'daily' or 'full' update.
 func getUpdateUrl(updateType string) (string, error) {
 	if updateType == "daily" {
 		return dailyUpdateUrl + getDayString(), nil
diff --git a/src/cif/types.go b/src/cif/types.go
index 9c8be6f..b78f248 100644
--- a/src/cif/types.go
+++ b/src/cif/types.go
@@ -1,5 +1,6 @@
 package cif
 
+// I believe that this is not used, instead I opted for the CifMetadata type.
 type CIFUpdate struct {
 	Timestamp int64
 	Sequence  int64
diff --git a/src/corpus/check.go b/src/corpus/check.go
index 418d6f3..b6d917b 100644
--- a/src/corpus/check.go
+++ b/src/corpus/check.go
@@ -9,6 +9,7 @@ import (
 	"go.uber.org/zap"
 )
 
+// Checks if the CORPUS Data needs updating, and carrys out the process if needed
 func CheckCorpus(cfg *helpers.Configuration) {
 	log.Msg.Debug("Checking age of CORPUS Data")
 	utime, err := dbAccess.CheckUpdateTime(dbAccess.CorpusCollection)
diff --git a/src/corpus/fetch.go b/src/corpus/fetch.go
index bccfbd2..10b6b3a 100644
--- a/src/corpus/fetch.go
+++ b/src/corpus/fetch.go
@@ -13,6 +13,7 @@ import (
 
 const url string = "https://publicdatafeeds.networkrail.co.uk/ntrod/SupportingFileAuthenticate?type=CORPUS"
 
+// Fetches CORPUS Data using the nrod.NrodDownload() function and returns the byte array
 func fetchCorpus(cfg *helpers.Configuration) (*[]byte, error) {
 	log.Msg.Info("Fetching CORPUS Data")
 	data, err := nrod.NrodDownload(url, cfg)
@@ -23,6 +24,7 @@ func fetchCorpus(cfg *helpers.Configuration) (*[]byte, error) {
 	return &data, nil
 }
 
+// Accepts CORPUS data as a byte array and formats it ready for database insertion
 func parseCorpusData(jsonData *[]byte) ([]database.CorpusEntry, error) {
 	log.Msg.Info("Unmarshalling CORPUS Data")
 
@@ -67,6 +69,7 @@ func parseCorpusData(jsonData *[]byte) ([]database.CorpusEntry, error) {
 	return corpusEntries, nil
 }
 
+// Removes empty fields from CORPUS entries
 func pruneCorpusEntries(corpusEntries []database.CorpusEntry) []database.CorpusEntry {
 	for i := range corpusEntries {
 		if corpusEntries[i].CRS == " " {
diff --git a/src/corpus/stations.go b/src/corpus/stations.go
index 68adeb5..d0e2954 100644
--- a/src/corpus/stations.go
+++ b/src/corpus/stations.go
@@ -2,6 +2,7 @@ package corpus
 
 import "git.fjla.uk/owlboard/go-types/pkg/database"
 
+// Removes non-station entities from the CORPUS Data, ready for insertion to the database (stations collection)
 func createStationEntries(corpusData []database.CorpusEntry) []database.StationEntry {
 	var stationEntries []database.StationEntry
 
diff --git a/src/corpus/update.go b/src/corpus/update.go
index 7c13ba5..fea5ded 100644
--- a/src/corpus/update.go
+++ b/src/corpus/update.go
@@ -7,6 +7,7 @@ import (
 	"go.uber.org/zap"
 )
 
+// Runs all stages of the CORPUS Update process
 func RunCorpusUpdate(cfg *helpers.Configuration) error {
 	resp, err := fetchCorpus(cfg)
 	if err != nil {
diff --git a/src/dbAccess/access.go b/src/dbAccess/access.go
index 0a93a9a..3c6e522 100644
--- a/src/dbAccess/access.go
+++ b/src/dbAccess/access.go
@@ -14,6 +14,7 @@ import (
 
 const timetableCollection string = "timetable"
 
+// CAUTION: Drops the collection named in collectionName
 func DropCollection(collectionName string) error {
 	database := MongoClient.Database(databaseName)
 	collection := database.Collection(collectionName)
@@ -27,6 +28,7 @@ func DropCollection(collectionName string) error {
 	return nil
 }
 
+// Checks the update time (unix timestamp) of the collection named in collectionName, uses 'type: collection' entries in the meta collection
 func CheckUpdateTime(collectionName string) (int64, error) {
 	database := MongoClient.Database(databaseName)
 	collection := database.Collection(metaCollection)
@@ -44,6 +46,7 @@ func CheckUpdateTime(collectionName string) (int64, error) {
 	return result.Updated, nil
 }
 
+// Sets a new update time (unix timestamp) of the collection named in collectionName.  The update time is calculated within the function.
 func SetUpdateTime(collectionName string) error {
 	log.Msg.Info("Setting update time", zap.String("collection", collectionName))
 	database := MongoClient.Database(databaseName)
@@ -70,6 +73,8 @@ func SetUpdateTime(collectionName string) error {
 	return nil
 }
 
+// Pushes the current version of this application to the data base 'versions' collection.
+// Currently uses the old name of mq-client
 func PushVersionToDb() {
 	version := database.Version{
 		Target:    "mq-client",
@@ -90,6 +95,7 @@ func PushVersionToDb() {
 	}
 }
 
+// Puts one item of the type `database.Service` to the database, used by the VSTP package which receives services one at a time
 func PutOneService(data database.Service) bool {
 	coll := MongoClient.Database(databaseName).Collection(timetableCollection)
 	_, err := coll.InsertOne(context.TODO(), data)
@@ -100,6 +106,7 @@ func PutOneService(data database.Service) bool {
 	return true
 }
 
+// Deletes one service from the database.
 func DeleteOneService(data database.DeleteQuery) bool {
 	coll := MongoClient.Database(databaseName).Collection(timetableCollection)
 	var filter = bson.D{
diff --git a/src/dbAccess/cif.go b/src/dbAccess/cif.go
index f829217..a0f657e 100644
--- a/src/dbAccess/cif.go
+++ b/src/dbAccess/cif.go
@@ -14,6 +14,8 @@ import (
 
 const Doctype = "CifMetadata"
 
+// The type describing the CifMetadata 'type' in the database.
+// This type will be moved to owlboard/go-types
 type CifMetadata struct {
 	Doctype       string    `json:"type"`
 	LastUpdate    time.Time `json:"lastUpdate"`
@@ -21,6 +23,7 @@ type CifMetadata struct {
 	LastSequence  int64     `json:"lastSequence"`
 }
 
+// Fetches the CifMetadata from the database, returns nil if no metadata exists - before first initialisation for example.
 func GetCifMetadata() (*CifMetadata, error) {
 	database := MongoClient.Database(databaseName)
 	collection := database.Collection(metaCollection)
@@ -38,6 +41,7 @@ func GetCifMetadata() (*CifMetadata, error) {
 	return &result, nil
 }
 
+// Uses upsert to Insert/Update the CifMetadata in the database
 func PutCifMetadata(metadata CifMetadata) bool {
 	database := MongoClient.Database(databaseName)
 	collection := database.Collection(metaCollection)
diff --git a/src/dbAccess/client.go b/src/dbAccess/client.go
index 3bf38a1..72586f7 100644
--- a/src/dbAccess/client.go
+++ b/src/dbAccess/client.go
@@ -16,12 +16,12 @@ const databaseName string = "owlboard"
 const CorpusCollection string = "corpus"
 const StationsCollection string = "stations"
 const metaCollection string = "meta"
-const cifMetaCollection string = "cifMeta"
 const TimetableCollection string = "timetable"
 
 // Provide the DB Connection to other functions
 var MongoClient (*mongo.Client)
 
+// Builds the DB URI based on the loaded configuration parameters
 func getDbUri(cfg *helpers.Configuration) string {
 	var uri = "mongodb://" + cfg.DbUser + ":" + cfg.DbPass + "@" + cfg.DbHost + ":" + cfg.DbPort
 	return uri
@@ -47,6 +47,7 @@ func InitDataAccess(cfg *helpers.Configuration) {
 	MongoClient = client
 }
 
+// Closes the connection to the database - used for cleanup functions
 func CloseMongoClient() {
 	if MongoClient != nil {
 		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
diff --git a/src/dbAccess/corpus.go b/src/dbAccess/corpus.go
index 2b9bbbb..9e80bf3 100644
--- a/src/dbAccess/corpus.go
+++ b/src/dbAccess/corpus.go
@@ -6,6 +6,7 @@ import (
 	"git.fjla.uk/owlboard/go-types/pkg/database"
 )
 
+// Puts an array of Corpus Documents into the database
 func PutManyCorpus(corpusData []database.CorpusEntry) error {
 	collection := MongoClient.Database(databaseName).Collection(CorpusCollection)
 
@@ -20,6 +21,7 @@ func PutManyCorpus(corpusData []database.CorpusEntry) error {
 	return nil
 }
 
+// Puts an array of Stations documents into the database
 func PutManyStations(stationsData []database.StationEntry) error {
 	collection := MongoClient.Database(databaseName).Collection(StationsCollection)
 
@@ -34,6 +36,7 @@ func PutManyStations(stationsData []database.StationEntry) error {
 	return nil
 }
 
+// Converts []database.CorpusEntry types into interface slices required to put them into the database
 func convertCorpusToInterfaceSlice(corpusData []database.CorpusEntry) []interface{} {
 	interfaceSlice := make([]interface{}, len(corpusData))
 	for i, doc := range corpusData {
@@ -42,6 +45,7 @@ func convertCorpusToInterfaceSlice(corpusData []database.CorpusEntry) []interfac
 	return interfaceSlice
 }
 
+// Converts []database.StationEntry types into interface slices required to put them into the database
 func convertStationsToInterfaceSlice(stationsData []database.StationEntry) []interface{} {
 	interfaceSlice := make([]interface{}, len(stationsData))
 	for i, doc := range stationsData {
diff --git a/src/helpers/basicAuth.go b/src/helpers/basicAuth.go
index 28c7111..f4760d5 100644
--- a/src/helpers/basicAuth.go
+++ b/src/helpers/basicAuth.go
@@ -2,6 +2,7 @@ package helpers
 
 import "encoding/base64"
 
+// Provides a BasicAuth string
 func BasicAuth(username, password string) string {
 	authString := username + ":" + password
 	return base64.StdEncoding.EncodeToString([]byte(authString))
diff --git a/src/helpers/config_loader.go b/src/helpers/config_loader.go
index a3012da..11ae40c 100644
--- a/src/helpers/config_loader.go
+++ b/src/helpers/config_loader.go
@@ -92,6 +92,7 @@ func LoadConfig() (*Configuration, error) {
 	return config, nil
 }
 
+// Applies configuration strings to the configuration struct
 func (c *Configuration) setConfigValue(key, value string) {
 	value = strings.TrimSpace(value)
 	switch key {
@@ -116,6 +117,7 @@ func (c *Configuration) setConfigValue(key, value string) {
 	}
 }
 
+// Provides a method to print the configuration struct.  Only when the DEBUG env is set to true
 func (c *Configuration) PrintConfig() {
 	if os.Getenv("DEBUG") == "true" {
 		fmt.Println("Configuration:")
diff --git a/src/helpers/vstp.go b/src/helpers/vstp.go
index 73a59c3..70debed 100644
--- a/src/helpers/vstp.go
+++ b/src/helpers/vstp.go
@@ -2,7 +2,6 @@ package helpers
 
 // An error with the VSTP messages is that speed values are shown incorrectly, but not for all services
 // This maps the displayed speed to the correct speed.
-
 var SpeedMap = map[string]string{
 	"22":  "10",
 	"34":  "15",
diff --git a/src/log/log.go b/src/log/log.go
index cf78950..b9732d6 100644
--- a/src/log/log.go
+++ b/src/log/log.go
@@ -9,6 +9,7 @@ import (
 
 var Msg *zap.Logger
 
+// Initialises the logger
 func init() {
 	var err error
 
diff --git a/src/messaging/client.go b/src/messaging/client.go
index f6b6d09..2afca13 100644
--- a/src/messaging/client.go
+++ b/src/messaging/client.go
@@ -8,6 +8,7 @@ import (
 
 var Client *stomp.Conn
 
+// Initialises the connection to the STOMP server
 func StompInit(cfg *helpers.Configuration) {
 	Client = dial(cfg.NrodUser, cfg.NrodPass)
 }