From ca45b7d28c553d89b4e4c28a9c0de89e47e44e58 Mon Sep 17 00:00:00 2001 From: per1234 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 c8ccb80e..2d60a7b9 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 0cf91f4d..6355ce39 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 41466916..7700bc79 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 a5c05ced..4083a958 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 32338ad3..3a9c4bb6 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 ce852bc2..a7bf84e7 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 ae53b492..401b33ec 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 1975517a..abe5b846 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 a46b1817..3697a4bd 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 a988b3ae..04fdac62 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 736ed095..37b44d6c 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 513706d1..dbfefc8f 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 2f7949d5..f0a24a37 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 e3de9bfc..e3d1ef25 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 4fcfc417..0c592892 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,