Improve/correct code comments

Various improvements and corrections to the comments in the code.

Author: per1234

Diff for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 [email protected].
 
-// 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 for: internal/rule/schema/parsevalidationresult.go

@@ -83,6 +83,7 @@ func ValidationErrorMatch(
 	)
 }
 
+// validationErrorMatch handles the recursion for ValidationErrorMatch().
 func validationErrorMatch(
 	instancePointerRegexp,
 	schemaPointerRegexp,