RHINENG-8141: update function doc comments to adhere to go conventions

evaluator/evaluate.go

@@ -165,7 +165,7 @@ func Evaluate(ctx context.Context, event *mqueue.PlatformEvent, inventoryID, eva
 	return nil
 }
 
-// Runs Evaluate method in Goroutines
+// RunEvaluate runs Evaluate method in Goroutines
 func runEvaluate(
 	ctx context.Context,
 	event mqueue.PlatformEvent, // makes a copy to avoid races
@@ -447,8 +447,8 @@ func commitWithObserve(tx *gorm.DB) error {
 	return nil
 }
 
-// First, load advisories and packages (including change evaluation).
-// Then, in a single transaction, do the deletions, updates, and insertions.
+// EvaluateAndStore first loads advisories and packages (including change evaluation)
+// and then executes all deletions, updates, and insertions in a single transaction.
 func evaluateAndStore(system *models.SystemPlatform,
 	vmaasData *vmaas.UpdatesV3Response, event *mqueue.PlatformEvent) error {
 	advisoriesByName, err := lazySaveAndLoadAdvisories(system, vmaasData)

evaluator/evaluate_advisories.go

@@ -12,7 +12,8 @@ import (
 	"gorm.io/gorm/clause"
 )
 
-// Lazy save missing advisories from reported, load stored ones, and evaluate changes between the two.
+// LazySaveAndLoadAdvisories lazy saves missing advisories from reported, loads stored ones from DB,
+// and evaluates changes between the two.
 func lazySaveAndLoadAdvisories(system *models.SystemPlatform, vmaasData *vmaas.UpdatesV3Response) (
 	extendedAdvisoryMap, error) {
 	if !enableAdvisoryAnalysis {
@@ -38,7 +39,7 @@ func lazySaveAndLoadAdvisories(system *models.SystemPlatform, vmaasData *vmaas.U
 	return merged, nil
 }
 
-// Create extendedAdvisoryMap from `stored` and `reported` advisories. It tracks changes between the two.
+// PasrseReported evaluates changes of type Add/Update/Keep and tracks them in extendedAdvisoryMap.
 func pasrseReported(stored SystemAdvisoryMap, reported map[string]int) (extendedAdvisoryMap, []string) {
 	extendedAdvisories := make(extendedAdvisoryMap, len(reported)+len(stored))
 	missingNames := make([]string, 0, len(reported))
@@ -104,7 +105,8 @@ func parseStored(stored SystemAdvisoryMap, reported map[string]int, extendedAdvi
 	}
 }
 
-// Evaluate changes to all advisories based on `stored` advisories from DB and `reported` advisories from VMaaS.
+// EvaluateChanges calls functions that evaluate all types of changes between stored advisories from DB
+// and reported advisories from VMaaS.
 func evaluateChanges(vmaasData *vmaas.UpdatesV3Response, stored SystemAdvisoryMap) (
 	extendedAdvisoryMap, error) {
 	reported := getReportedAdvisories(vmaasData)
@@ -120,7 +122,7 @@ func evaluateChanges(vmaasData *vmaas.UpdatesV3Response, stored SystemAdvisoryMa
 	return extendedAdvisories, nil
 }
 
-// From names reported by VMaaS, find advisories missing in the DB and lazy-save them.
+// LazySaveAdvisories finds advisories reported by VMaaS and missing in the DB and lazy saves them.
 func lazySaveAdvisories(vmaasData *vmaas.UpdatesV3Response, inventoryID string) error {
 	reportedNames := getReportedAdvisoryNames(vmaasData)
 	if len(reportedNames) < 1 {
@@ -186,7 +188,7 @@ func getAdvisoryMetadataByNames(names []string) (models.AdvisoryMetadataSlice, e
 	return metadata, err
 }
 
-// Determine if advisories from DB are properly stored based on advisory metadata existence.
+// GetMissingAdvisories determines if advisories from DB are properly stored based on advisory metadata existence.
 func getMissingAdvisories(advisoryNames []string) ([]string, error) {
 	advisoryMetadata, err := getAdvisoryMetadataByNames(advisoryNames)
 	if err != nil {

evaluator/evaluate_packages.go

@@ -35,7 +35,7 @@ func lazySaveAndLoadPackages(system *models.SystemPlatform, vmaasData *vmaas.Upd
 	return pkgByName, installed, installable, applicable, nil
 }
 
-// Add unknown EVRAs into the db if needed
+// LazySavePackages adds unknown EVRAs into the db if needed.
 func lazySavePackages(vmaasData *vmaas.UpdatesV3Response) error {
 	if !enableLazyPackageSave {
 		return nil
@@ -89,7 +89,7 @@ func getMissingPackage(nevra string) *models.Package {
 	return &pkg
 }
 
-// Get packages with known name but version missing in db/cache
+// GetMissingPackages gets packages with a known name but a version missing in db/cache.
 func getMissingPackages(vmaasData *vmaas.UpdatesV3Response) models.PackageSlice {
 	updates := vmaasData.GetUpdateList()
 	packages := make(models.PackageSlice, 0, len(updates))
@@ -130,7 +130,7 @@ func updatePackageNameDB(missing *models.PackageName) error {
 	return nil
 }
 
-// Find relevant package data based on vmaas results
+// LoadPackages finds relevant package data based on vmaas results.
 func loadPackages(system *models.SystemPlatform, vmaasData *vmaas.UpdatesV3Response) (
 	map[string]namedPackage, int, int, int, error) {
 	defer utils.ObserveSecondsSince(time.Now(), evaluationPartDuration.WithLabelValues("packages-load"))