From ca45b7d28c553d89b4e4c28a9c0de89e47e44e58 Mon Sep 17 00:00:00 2001
From: per1234 <accounts@perglass.com>
Date: Tue, 22 Dec 2020 22:56:37 -0800
Subject: [PATCH] Improve/correct code comments

Various improvements and corrections to the comments in the code.
---
 docs/build.py                                           | 2 +-
 internal/configuration/configuration.go                 | 4 ++++
 internal/configuration/rulemode/rulemode.go             | 1 +
 internal/project/packageindex/packageindex.go           | 1 +
 internal/project/platform/platform.go                   | 1 +
 internal/project/project.go                             | 1 +
 internal/project/projectdata/library.go                 | 3 +--
 internal/project/projectdata/platform.go                | 2 +-
 internal/result/result.go                               | 9 ++++++++-
 internal/rule/rule.go                                   | 1 +
 internal/rule/rulefunction/library.go                   | 6 +++---
 internal/rule/rulefunction/rulefunction.go              | 1 +
 internal/rule/ruleresult/ruleresult.go                  | 1 +
 internal/rule/schema/compliancelevel/compliancelevel.go | 2 +-
 internal/rule/schema/parsevalidationresult.go           | 1 +
 15 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/docs/build.py b/docs/build.py
index c8ccb80e7..2d60a7b97 100644
--- a/docs/build.py
+++ b/docs/build.py
@@ -47,7 +47,7 @@
 #
 # In order to avoid unwanted changes to the public website hosting the arduino-lint documentation, only Mike is allowed
 # to push changes to the `gh-pages` branch, and this only happens from within the CI, in the "Publish documentation"
-# workflow: https://github.com/arduino/arduino-lint/blob/master/.github/workflows/publish-docs.yml
+# workflow: https://github.com/arduino/arduino-lint/blob/main/.github/workflows/publish-docs.yml
 #
 # The CI is responsible for guessing which version of arduino-lint we're building docs for, so that generated content
 # will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex,
diff --git a/internal/configuration/configuration.go b/internal/configuration/configuration.go
index 0cf91f4dc..6355ce39b 100644
--- a/internal/configuration/configuration.go
+++ b/internal/configuration/configuration.go
@@ -195,12 +195,14 @@ func Verbose() bool {
 
 var versionMode bool
 
+// VersionMode returns the --version setting.
 func VersionMode() bool {
 	return versionMode
 }
 
 var version string
 
+// Version returns the build version.
 func Version() string {
 	return version
 }
@@ -214,6 +216,7 @@ func Commit() string {
 
 var buildTimestamp string
 
+// BuildTimestamp returns the timestamp of the build.
 func BuildTimestamp() string {
 	return buildTimestamp
 }
@@ -225,6 +228,7 @@ func TargetPaths() paths.PathList {
 	return targetPaths
 }
 
+// EnableLogging enables or disables logging debug output.
 func EnableLogging(enable bool) {
 	if enable {
 		logrus.SetOutput(defaultLogOutput) // Enable log output.
diff --git a/internal/configuration/rulemode/rulemode.go b/internal/configuration/rulemode/rulemode.go
index 41466916c..7700bc79f 100644
--- a/internal/configuration/rulemode/rulemode.go
+++ b/internal/configuration/rulemode/rulemode.go
@@ -96,6 +96,7 @@ func Modes(defaultRuleModes map[projecttype.Type]map[Type]bool, customRuleModes
 	return ruleModes
 }
 
+// Compliance returns the tool configuration's compliance setting name.
 func Compliance(ruleModes map[Type]bool) string {
 	for key, value := range ruleModes {
 		if value && (key == Strict || key == Specification || key == Permissive) {
diff --git a/internal/project/packageindex/packageindex.go b/internal/project/packageindex/packageindex.go
index a5c05cede..4083a958d 100644
--- a/internal/project/packageindex/packageindex.go
+++ b/internal/project/packageindex/packageindex.go
@@ -53,6 +53,7 @@ func HasValidFilename(filePath *paths.Path, officialRuleMode bool) bool {
 	return regex.MatchString(filename)
 }
 
+// Find searches the provided path for a file that has a name resembling a package index and returns the path to that file.
 func Find(folderPath *paths.Path) (*paths.Path, error) {
 	exist, err := folderPath.ExistCheck()
 	if !exist {
diff --git a/internal/project/platform/platform.go b/internal/project/platform/platform.go
index 32338ad35..3a9c4bb65 100644
--- a/internal/project/platform/platform.go
+++ b/internal/project/platform/platform.go
@@ -55,6 +55,7 @@ var bundledLibrariesFolderNames = map[string]struct{}{
 	"libraries": empty,
 }
 
+// BundledLibrariesFolderNames returns a list of supported names for the platform bundled libraries folder.
 func BundledLibrariesFolderNames() []string {
 	folderNames := make([]string, 0, len(bundledLibrariesFolderNames))
 	for folderName := range bundledLibrariesFolderNames {
diff --git a/internal/project/project.go b/internal/project/project.go
index ce852bc2a..a7bf84e75 100644
--- a/internal/project/project.go
+++ b/internal/project/project.go
@@ -51,6 +51,7 @@ func FindProjects() ([]Type, error) {
 	return foundProjects, nil
 }
 
+// findProjects handles the recursion for FindProjects().
 func findProjects(targetPath *paths.Path) ([]Type, error) {
 	var foundProjects []Type
 
diff --git a/internal/project/projectdata/library.go b/internal/project/projectdata/library.go
index ae53b4927..401b33ecd 100644
--- a/internal/project/projectdata/library.go
+++ b/internal/project/projectdata/library.go
@@ -32,14 +32,13 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
-// Initialize gathers the library rule data for the specified project.
+// InitializeForLibrary gathers the library rule data for the specified project.
 func InitializeForLibrary(project project.Type) {
 	var err error
 
 	libraryProperties, libraryPropertiesLoadError = libraryproperties.Properties(project.Path)
 	if libraryPropertiesLoadError != nil {
 		logrus.Errorf("Error loading library.properties from %s: %s", project.Path, libraryPropertiesLoadError)
-		// TODO: can I even do this?
 		libraryPropertiesSchemaValidationResult = nil
 	} else {
 		libraryPropertiesSchemaValidationResult = libraryproperties.Validate(libraryProperties)
diff --git a/internal/project/projectdata/platform.go b/internal/project/projectdata/platform.go
index 1975517ab..abe5b846b 100644
--- a/internal/project/projectdata/platform.go
+++ b/internal/project/projectdata/platform.go
@@ -21,7 +21,7 @@ import (
 	"github.com/arduino/go-properties-orderedmap"
 )
 
-// Initialize gathers the platform rule data for the specified project.
+// InitializeForPlatform gathers the platform rule data for the specified project.
 func InitializeForPlatform(project project.Type) {
 	boardsTxt, boardsTxtLoadError = boardstxt.Properties(ProjectPath())
 }
diff --git a/internal/result/result.go b/internal/result/result.go
index a46b18173..3697a4bdd 100644
--- a/internal/result/result.go
+++ b/internal/result/result.go
@@ -41,12 +41,14 @@ type Type struct {
 	Summary       summaryReportType           `json:"summary"`
 }
 
+// toolConfigurationReportType is the type for the arduino-lint tool configuration.
 type toolConfigurationReportType struct {
 	Paths       paths.PathList `json:"paths"`
 	ProjectType string         `json:"projectType"`
 	Recursive   bool           `json:"recursive"`
 }
 
+// projectReportType is the type for the individual project reports.
 type projectReportType struct {
 	Path          *paths.Path                    `json:"path"`
 	ProjectType   string                         `json:"projectType"`
@@ -55,12 +57,14 @@ type projectReportType struct {
 	Summary       summaryReportType              `json:"summary"`
 }
 
+// projectConfigurationReportType is the type for the individual project tool configurations.
 type projectConfigurationReportType struct {
 	Compliance     string `json:"compliance"`
 	LibraryManager string `json:"libraryManager"`
 	Official       bool   `json:"official"`
 }
 
+// ruleReportType is the type of the rule reports.
 type ruleReportType struct {
 	Category    string `json:"category"`
 	Subcategory string `json:"subcategory"`
@@ -72,6 +76,7 @@ type ruleReportType struct {
 	Message     string `json:"message"`
 }
 
+// summaryReportType is the type of the rule result summary reports.
 type summaryReportType struct {
 	Pass         bool `json:"pass"`
 	WarningCount int  `json:"warningCount"`
@@ -210,11 +215,12 @@ func (results Type) SummaryText() string {
 	return fmt.Sprintf("Finished linting projects. Results:\nWarning count: %v\nError count: %v\nRules passed: %v", results.Summary.WarningCount, results.Summary.ErrorCount, results.Summary.Pass)
 }
 
-// JSONReport returns a JSON formatted report of rules on all projects.
+// JSONReport returns a JSON formatted report of rules on all projects in string encoding.
 func (results Type) JSONReport() string {
 	return string(results.jsonReportRaw())
 }
 
+// jsonReportRaw returns the report marshalled into JSON format in byte encoding.
 func (results Type) jsonReportRaw() []byte {
 	reportJSON, err := json.MarshalIndent(results, "", "  ")
 	if err != nil {
@@ -251,6 +257,7 @@ func (results Type) Passed() bool {
 	return results.Summary.Pass
 }
 
+// getProjectReportIndex returns the index of the existing entry in the results.Projects array for the given project, or the next available index if there is no existing entry.
 func (results Type) getProjectReportIndex(projectPath *paths.Path) (bool, int) {
 	var index int
 	var projectReport projectReportType
diff --git a/internal/rule/rule.go b/internal/rule/rule.go
index a988b3aed..04fdac62b 100644
--- a/internal/rule/rule.go
+++ b/internal/rule/rule.go
@@ -69,6 +69,7 @@ func shouldRun(ruleConfiguration ruleconfiguration.Type, currentProject project.
 	return IsEnabled(ruleConfiguration, configurationRuleModes)
 }
 
+// IsEnabled returns whether a given rule is enabled under a given tool configuration.
 func IsEnabled(ruleConfiguration ruleconfiguration.Type, configurationRuleModes map[rulemode.Type]bool) (bool, error) {
 	for _, disableMode := range ruleConfiguration.DisableModes {
 		if configurationRuleModes[disableMode] {
diff --git a/internal/rule/rulefunction/library.go b/internal/rule/rulefunction/library.go
index 736ed0952..37b44d6ce 100644
--- a/internal/rule/rulefunction/library.go
+++ b/internal/rule/rulefunction/library.go
@@ -481,7 +481,7 @@ func LibraryPropertiesNameFieldContainsLibrary() (result ruleresult.Type, output
 	return ruleresult.Pass, ""
 }
 
-// LibraryPropertiesNameFieldDuplicate checks whether there is an existing entry in the Library Manager index using the the library.properties `name` value.
+// LibraryPropertiesNameFieldDuplicate checks whether there is an existing entry in the Library Manager index using the library.properties `name` value.
 func LibraryPropertiesNameFieldDuplicate() (result ruleresult.Type, output string) {
 	if projectdata.LibraryPropertiesLoadError() != nil {
 		return ruleresult.NotRun, "Couldn't load library.properties"
@@ -499,7 +499,7 @@ func LibraryPropertiesNameFieldDuplicate() (result ruleresult.Type, output strin
 	return ruleresult.Pass, ""
 }
 
-// LibraryPropertiesNameFieldNotInIndex checks whether there is no existing entry in the Library Manager index using the the library.properties `name` value.
+// LibraryPropertiesNameFieldNotInIndex checks whether there is no existing entry in the Library Manager index using the library.properties `name` value.
 func LibraryPropertiesNameFieldNotInIndex() (result ruleresult.Type, output string) {
 	if projectdata.LibraryPropertiesLoadError() != nil {
 		return ruleresult.NotRun, "Couldn't load library.properties"
@@ -1019,7 +1019,7 @@ func LibraryPropertiesArchitecturesFieldLTMinLength() (result ruleresult.Type, o
 	return ruleresult.Pass, ""
 }
 
-// LibraryPropertiesArchitecturesFieldAlias checks whether an alias architecture name is present, but not its true Arduino architecture name.
+// LibraryPropertiesArchitecturesFieldSoloAlias checks whether an alias architecture name is present, but not its true Arduino architecture name.
 func LibraryPropertiesArchitecturesFieldSoloAlias() (result ruleresult.Type, output string) {
 	if projectdata.LibraryPropertiesLoadError() != nil {
 		return ruleresult.NotRun, "Couldn't load library.properties"
diff --git a/internal/rule/rulefunction/rulefunction.go b/internal/rule/rulefunction/rulefunction.go
index 513706d1d..dbfefc8f4 100644
--- a/internal/rule/rulefunction/rulefunction.go
+++ b/internal/rule/rulefunction/rulefunction.go
@@ -114,6 +114,7 @@ func containsMisspelledPathBaseName(pathList paths.PathList, correctBaseName str
 	return nil, false
 }
 
+// containsIncorrectPathBaseCase checks whether the list of paths contains an element with base name matching the provided query in all bug case.
 func containsIncorrectPathBaseCase(pathList paths.PathList, correctBaseName string) (*paths.Path, bool) {
 	for _, path := range pathList {
 		if path.Base() == correctBaseName {
diff --git a/internal/rule/ruleresult/ruleresult.go b/internal/rule/ruleresult/ruleresult.go
index 2f7949d57..f0a24a376 100644
--- a/internal/rule/ruleresult/ruleresult.go
+++ b/internal/rule/ruleresult/ruleresult.go
@@ -16,6 +16,7 @@
 // Package ruleresult defines the possible result values returned by a rule.
 package ruleresult
 
+// Type is the type for rule results.
 //go:generate stringer -type=Type -linecomment
 type Type int
 
diff --git a/internal/rule/schema/compliancelevel/compliancelevel.go b/internal/rule/schema/compliancelevel/compliancelevel.go
index e3de9bfc1..e3d1ef25d 100644
--- a/internal/rule/schema/compliancelevel/compliancelevel.go
+++ b/internal/rule/schema/compliancelevel/compliancelevel.go
@@ -13,7 +13,7 @@
 // Arduino software without disclosing the source code of your own applications.
 // To purchase a commercial license, send an email to license@arduino.cc.
 
-// Package compliance level defines the levels of specification compliance.
+// Package compliancelevel defines the levels of specification compliance.
 package compliancelevel
 
 // Type is the type for the compliance levels.
diff --git a/internal/rule/schema/parsevalidationresult.go b/internal/rule/schema/parsevalidationresult.go
index 4fcfc4178..0c5928923 100644
--- a/internal/rule/schema/parsevalidationresult.go
+++ b/internal/rule/schema/parsevalidationresult.go
@@ -83,6 +83,7 @@ func ValidationErrorMatch(
 	)
 }
 
+// validationErrorMatch handles the recursion for ValidationErrorMatch().
 func validationErrorMatch(
 	instancePointerRegexp,
 	schemaPointerRegexp,