From f30c704794da2a3e9842e5ecfc539b4dd641695d Mon Sep 17 00:00:00 2001
From: Manuel Carrer <manuel.carrer@zohomail.eu>
Date: Thu, 14 Nov 2024 13:31:13 +0100
Subject: [PATCH] Add some docs about implemented `DumpFunction`s

---
 migrations/kdvh/dump_functions.go | 51 +++++--------------------------
 migrations/kdvh/table.go          |  1 +
 2 files changed, 9 insertions(+), 43 deletions(-)

diff --git a/migrations/kdvh/dump_functions.go b/migrations/kdvh/dump_functions.go
index 56f8d52..adc1930 100644
--- a/migrations/kdvh/dump_functions.go
+++ b/migrations/kdvh/dump_functions.go
@@ -60,49 +60,8 @@ func fetchYearRange(tableName, station string, conn *sql.DB) (int64, int64, erro
 	return begin, end, nil
 }
 
-func dumpByYearDataOnly(path string, meta DumpMeta, conn *sql.DB) error {
-	begin, end, err := fetchYearRange(meta.dataTable, meta.station, conn)
-	if err != nil {
-		slog.Error(meta.logStr + err.Error())
-		return err
-	}
-
-	query := fmt.Sprintf(
-		`SELECT dato AS time, %[1]s AS data, '' AS flag FROM %[2]s 
-        WHERE %[1]s IS NOT NULL
-        AND stnr = $1 AND TO_CHAR(dato, 'yyyy') = $2`,
-		meta.element,
-		meta.dataTable,
-	)
-
-	for year := begin; year < end; year++ {
-		yearPath := filepath.Join(path, fmt.Sprint(year))
-		if err := os.MkdirAll(yearPath, os.ModePerm); err != nil {
-			slog.Error(meta.logStr + err.Error())
-			continue
-		}
-
-		filename := filepath.Join(yearPath, meta.element+".csv")
-		if err := fileExists(filename, meta.overwrite); err != nil {
-			slog.Warn(meta.logStr + err.Error())
-			continue
-		}
-
-		rows, err := conn.Query(query, meta.station, year)
-		if err != nil {
-			slog.Error(meta.logStr + fmt.Sprint("Could not query KDVH: ", err))
-			continue
-		}
-
-		if err := dumpToFile(filename, rows); err != nil {
-			slog.Error(meta.logStr + err.Error())
-			continue
-		}
-	}
-
-	return nil
-}
-
+// This function is used when the table contains large amount of data
+// (T_SECOND, T_MINUTE, T_10MINUTE)
 func dumpByYear(path string, meta DumpMeta, conn *sql.DB) error {
 	dataBegin, dataEnd, err := fetchYearRange(meta.dataTable, meta.station, conn)
 	if err != nil {
@@ -196,6 +155,8 @@ func dumpHomogenMonth(path string, meta DumpMeta, conn *sql.DB) error {
 	return nil
 }
 
+// This function is used to dump tables that don't have a FLAG table,
+// (T_METARDATA, T_HOMOGEN_DIURNAL)
 func dumpDataOnly(path string, meta DumpMeta, conn *sql.DB) error {
 	filename := filepath.Join(path, meta.element+".csv")
 	if err := fileExists(filename, meta.overwrite); err != nil {
@@ -224,6 +185,9 @@ func dumpDataOnly(path string, meta DumpMeta, conn *sql.DB) error {
 	return nil
 }
 
+// This is the default dump function.
+// It selects both data and flag tables for a specific (station, element) pair,
+// and then performs a full outer join on the two subqueries
 func dumpDataAndFlags(path string, meta DumpMeta, conn *sql.DB) error {
 	filename := filepath.Join(path, meta.element+".csv")
 	if err := fileExists(filename, meta.overwrite); err != nil {
@@ -262,6 +226,7 @@ func dumpDataAndFlags(path string, meta DumpMeta, conn *sql.DB) error {
 	return nil
 }
 
+// Dumps queried rows to file
 func dumpToFile(filename string, rows *sql.Rows) error {
 	lines, err := sortRows(rows)
 	if err != nil {
diff --git a/migrations/kdvh/table.go b/migrations/kdvh/table.go
index 2eee55a..bb2ffc8 100644
--- a/migrations/kdvh/table.go
+++ b/migrations/kdvh/table.go
@@ -36,6 +36,7 @@ type Table struct {
 	importUntil   int             // Import data only until the year specified by this field. If this field is not explicitly set, table import is skipped.
 }
 
+// Implementation of these functions can be found in `dump_functions.go`
 type DumpFunction func(path string, meta DumpMeta, conn *sql.DB) error
 type DumpMeta struct {
 	element   string