Merge pull request #134 from arduino/per1234/improve-comments

Improve/correct code comments

Author: per1234

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,

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.

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) {

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 {

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 {

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
 

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)

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())
 }

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

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] {