Add/improve code comments

Author: per1234

check/check.go

@@ -1,3 +1,4 @@
+// Package check runs checks on a project.
 package check
 
 import (
@@ -17,6 +18,7 @@ import (
 	"github.com/arduino/arduino-cli/cli/feedback"
 )
 
+// shouldRun returns whether a given check should be run for the given project under the current tool configuration.
 func shouldRun(checkConfiguration checkconfigurations.Type, currentProject project.Type) bool {
 	configurationCheckModes := configuration.CheckModes(currentProject.SuperprojectType)
 
@@ -53,6 +55,7 @@ func shouldRun(checkConfiguration checkconfigurations.Type, currentProject proje
 	return false
 }
 
+// message fills the message template provided by the check configuration with the check output.
 // TODO: make checkOutput a struct to allow for more advanced message templating
 func message(templateText string, checkOutput string) string {
 	messageTemplate := template.Must(template.New("messageTemplate").Parse(templateText))
@@ -63,6 +66,7 @@ func message(templateText string, checkOutput string) string {
 	return messageBuffer.String()
 }
 
+// RunChecks runs all checks for the given project and outputs the results.
 func RunChecks(project project.Type) {
 	fmt.Printf("Checking %s in %s\n", project.ProjectType.String(), project.Path.String())
 

check/checkconfigurations/checkconfigurations.go

@@ -1,3 +1,11 @@
+/*
+Package checkconfigurations defines the configuration of each check:
+- metadata
+- output template
+- under which conditions it's enabled
+- the level of a failure
+- which function implements it
+*/
 package checkconfigurations
 
 import (
@@ -6,29 +14,24 @@ import (
 	"github.com/arduino/arduino-check/project/projecttype"
 )
 
+// Type is the type for check configurations.
 type Type struct {
-	ProjectType projecttype.Type
-	// Arbitrary text for the log
-	Category    string
-	Subcategory string
-	// Unique check identifier
-	ID          string
-	Name        string
-	Description string
-	// The warning/error message template displayed when the check fails
-	// The check function output will be filled into the template
-	MessageTemplate string
-	// The following fields define under which tool configuration modes the check will run
-	// Check is disabled when tool is in any of these modes
-	DisableModes []checkmode.Type
-	// Check is only enabled when tool is in one of these modes
-	EnableModes []checkmode.Type
-	// The following fields define the check level in each configuration mode
-	InfoModes    []checkmode.Type
-	WarningModes []checkmode.Type
-	ErrorModes   []checkmode.Type
-	// The function that implements the check
-	CheckFunction checkfunctions.Type
+	ProjectType projecttype.Type // The project type the check applies to.
+	// The following fields provide arbitrary text for the tool output associated with each check:
+	Category        string
+	Subcategory     string
+	ID              string // Unique check identifier: <project type identifier (L|S|P|I)><category identifier><number>
+	Name            string // Short description of the check.
+	Description     string // Supplemental information about the check.
+	MessageTemplate string // The warning/error message template displayed when the check fails. Will be filled by check function output.
+	// The following fields define under which tool configuration modes the check will run:
+	DisableModes []checkmode.Type // Check is disabled when tool is in any of these modes.
+	EnableModes  []checkmode.Type // Check is only enabled when tool is in one of these modes.
+	// The following fields define the check level in each configuration mode:
+	InfoModes     []checkmode.Type    // Failure of the check only results in an informational message.
+	WarningModes  []checkmode.Type    // Failure of the check is considered a warning.
+	ErrorModes    []checkmode.Type    // Failure of the check is considered an error.
+	CheckFunction checkfunctions.Type // The function that implements the check.
 }
 
 // Checks is an array of structs that define the configuration of each check.

check/checkdata/checkdata.go

@@ -1,3 +1,7 @@
+/*
+Package checkdata handles the collection of data specific to a project before running the checks on it.
+This is for data required by multiple checks.
+*/
 package checkdata
 
 import (
@@ -11,34 +15,41 @@ import (
 
 var projectType projecttype.Type
 
+// ProjectType returns the type of the project being checked.
 func ProjectType() projecttype.Type {
 	return projectType
 }
 
 var projectPath *paths.Path
 
+// ProjectPath returns the path to the project being checked.
 func ProjectPath() *paths.Path {
 	return projectPath
 }
 
 var libraryPropertiesLoadError error
 
+// LibraryPropertiesLoadError returns the error output from loading the library.properties metadata file.
 func LibraryPropertiesLoadError() error {
 	return libraryPropertiesLoadError
 }
 
 var libraryProperties *properties.Map
 
+// LibraryProperties returns the data from the library.properties metadata file
 func LibraryProperties() *properties.Map {
 	return libraryProperties
 }
 
 var libraryPropertiesSchemaValidationResult *gojsonschema.Result
 
+// LibraryPropertiesSchemaValidationResult returns the result of validating library.properties against the JSON schema.
+// See: https://github.com/xeipuuv/gojsonschema
 func LibraryPropertiesSchemaValidationResult() *gojsonschema.Result {
 	return libraryPropertiesSchemaValidationResult
 }
 
+// Initialize gathers the check data for the specified project.
 func Initialize(project project.Type) {
 	projectType = project.ProjectType
 	projectPath = project.Path

check/checkfunctions/checkfunctions.go

@@ -1,8 +1,10 @@
+// Package checkfunctions contains the functions that implement each check.
 package checkfunctions
 
 import (
 	"github.com/arduino/arduino-check/check/checkresult"
 )
 
-// output is the contextual information that will be added to the stock message
+// Type is the function signature for the check functions.
+// The `output` result is the contextual information that will be inserted into the check's message template
 type Type func() (result checkresult.Type, output string)

check/checkfunctions/library.go

@@ -1,5 +1,7 @@
 package checkfunctions
 
+// The check functions for libraries.
+
 import (
 	"github.com/arduino/arduino-check/check/checkdata"
 	"github.com/arduino/arduino-check/check/checkresult"

check/checkfunctions/sketch.go

@@ -1,5 +1,7 @@
 package checkfunctions
 
+// The check functions for sketches.
+
 import (
 	"github.com/arduino/arduino-check/check/checkdata"
 	"github.com/arduino/arduino-check/check/checkresult"

check/checklevel/checklevel.go

@@ -1,3 +1,4 @@
+// Package checklevel defines the level assigned to a check failure.
 package checklevel
 
 import (
@@ -8,17 +9,19 @@ import (
 	"github.com/arduino/arduino-check/configuration/checkmode"
 )
 
+// Type is the type for the check levels.
 //go:generate stringer -type=Type -linecomment
 type Type int
 
-// Line comments set the string for each level
+// The line comments set the string for each level.
 const (
 	Info    Type = iota // info
 	Warning             // warning
 	Error               // error
 	Notice              // notice
 )
 
+// CheckLevel determines the check level assigned to failure of the given check under the current tool configuration.
 func CheckLevel(checkConfiguration checkconfigurations.Type) (Type, error) {
 	configurationCheckModes := configuration.CheckModes(checkConfiguration.ProjectType)
 	for _, errorMode := range checkConfiguration.ErrorModes {

check/checkresult/checkresult.go

@@ -1,3 +1,4 @@
+// Package checkresult defines the possible result values returned by a check.
 package checkresult
 
 //go:generate stringer -type=Type -linecomment

configuration/checkmode/checkmode.go

@@ -1,10 +1,12 @@
+// Package checkmode defines the tool configuration options that affect checks.
 package checkmode
 
 import (
 	"github.com/arduino/arduino-check/project/projecttype"
 	"github.com/sirupsen/logrus"
 )
 
+// Type is the type for check modes.
 type Type int
 
 //go:generate stringer -type=Type -linecomment
@@ -17,10 +19,10 @@ const (
 	Default                              // default
 )
 
+// Modes merges the default check mode values for the given superproject type with any user-specified check mode settings.
 func Modes(defaultCheckModes map[projecttype.Type]map[Type]bool, customCheckModes map[Type]bool, superprojectType projecttype.Type) map[Type]bool {
 	checkModes := make(map[Type]bool)
 
-	// Merge the default settings with any custom settings specified by the user
 	for key, defaultValue := range defaultCheckModes[superprojectType] {
 		customCheckModeValue, customCheckModeIsConfigured := customCheckModes[key]
 		if customCheckModeIsConfigured {

configuration/configuration.go

@@ -1,3 +1,4 @@
+// Package configuration handles the configuration of the arduino-check tool.
 package configuration
 
 import (
@@ -8,6 +9,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Initialize sets up the tool configuration according to defaults and user-specified options.
 func Initialize() {
 	setDefaults()
 	// TODO configuration according to command line input
@@ -33,24 +35,28 @@ func Initialize() {
 
 var customCheckModes = make(map[checkmode.Type]bool)
 
+// CheckModes returns the check modes configuration for the given project type.
 func CheckModes(superprojectType projecttype.Type) map[checkmode.Type]bool {
 	return checkmode.Modes(defaultCheckModes, customCheckModes, superprojectType)
 }
 
 var superprojectType projecttype.Type
 
+// SuperprojectType returns the superproject type filter configuration.
 func SuperprojectType() projecttype.Type {
 	return superprojectType
 }
 
 var recursive bool
 
+// Recursive returns the recursive project search configuration value.
 func Recursive() bool {
 	return recursive
 }
 
 var targetPath *paths.Path
 
+// TargetPath returns the projects search path.
 func TargetPath() *paths.Path {
 	return targetPath
 }

configuration/defaults.go

@@ -1,5 +1,7 @@
 package configuration
 
+// The default configuration settings.
+
 import (
 	"github.com/arduino/arduino-check/configuration/checkmode"
 	"github.com/arduino/arduino-check/project/projecttype"

project/library/library.go

@@ -1,3 +1,4 @@
+// Package library provides functions specific to checking Arduino libraries.
 package library
 
 import (
@@ -6,13 +7,14 @@ import (
 
 var empty struct{}
 
-// reference: https://github.com/arduino/arduino-cli/blob/0.13.0/arduino/libraries/libraries.go#L167
+// Reference: https://github.com/arduino/arduino-cli/blob/0.13.0/arduino/libraries/libraries.go#L167
 var headerFileValidExtensions = map[string]struct{}{
 	".h":   empty,
 	".hpp": empty,
 	".hh":  empty,
 }
 
+// HasHeaderFileValidExtension returns whether the file at the given path has a valid library header file extension.
 func HasHeaderFileValidExtension(filePath *paths.Path) bool {
 	_, hasHeaderFileValidExtension := headerFileValidExtensions[filePath.Ext()]
 	if hasHeaderFileValidExtension {
@@ -21,10 +23,12 @@ func HasHeaderFileValidExtension(filePath *paths.Path) bool {
 	return false
 }
 
+// See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata
 var metadataFilenames = map[string]struct{}{
 	"library.properties": empty,
 }
 
+// IsMetadataFile returns whether the file at the given path is an Arduino library metadata file.
 func IsMetadataFile(filePath *paths.Path) bool {
 	_, isMetadataFile := metadataFilenames[filePath.Base()]
 	if isMetadataFile {

project/library/libraryproperties/libraryproperties.go

@@ -1,3 +1,4 @@
+// Package libraryproperties provides functions for working with the library.properties Arduino library metadata file.
 package libraryproperties
 
 import (
@@ -10,6 +11,7 @@ import (
 	"github.com/xeipuuv/gojsonschema"
 )
 
+// Properties parses the library.properties from the given path and returns the data.
 func Properties(libraryPath *paths.Path) (*properties.Map, error) {
 	libraryProperties, err := properties.Load(libraryPath.Join("library.properties").String())
 	if err != nil {
@@ -18,6 +20,7 @@ func Properties(libraryPath *paths.Path) (*properties.Map, error) {
 	return libraryProperties, nil
 }
 
+// Validate validates library.properties data against the JSON schema.
 func Validate(libraryProperties *properties.Map) *gojsonschema.Result {
 	workingPath, _ := os.Getwd()
 	schemaPath := paths.New(workingPath).Join("arduino-library-properties-schema.json")
@@ -38,14 +41,18 @@ func Validate(libraryProperties *properties.Map) *gojsonschema.Result {
 	return result
 }
 
+// FieldMissing returns whether the given required field is missing from library.properties.
 func FieldMissing(fieldName string, validationResult *gojsonschema.Result) bool {
 	return ValidationErrorMatch("required", "(root)", fieldName+" is required", validationResult)
 }
 
+// FieldPatternMismatch returns whether the given field did not match the regular expression defined in the JSON schema.
 func FieldPatternMismatch(fieldName string, validationResult *gojsonschema.Result) bool {
 	return ValidationErrorMatch("pattern", fieldName, "", validationResult)
 }
 
+// ValidationErrorMatch returns whether the given query matches against the JSON schema validation error.
+// See: https://github.com/xeipuuv/gojsonschema#working-with-errors
 func ValidationErrorMatch(typeQuery string, fieldQuery string, descriptionQuery string, validationResult *gojsonschema.Result) bool {
 	if validationResult.Valid() {
 		// No error, so nothing to match

project/packageindex/packageindex.go

@@ -1,3 +1,7 @@
+/*
+Package packageindex provides functions specific to checking the package index files of the Arduino Boards Manager.
+See: https://arduino.github.io/arduino-cli/latest/package_index_json-specification
+*/
 package packageindex
 
 import (
@@ -8,10 +12,12 @@ import (
 
 var empty struct{}
 
+// Reference: https://arduino.github.io/arduino-cli/latest/package_index_json-specification/#naming-of-the-json-index-file
 var validExtensions = map[string]struct{}{
 	".json": empty,
 }
 
+// HasValidExtension returns whether the file at the given path has a valid package index extension.
 func HasValidExtension(filePath *paths.Path) bool {
 	_, hasValidExtension := validExtensions[filePath.Ext()]
 	if hasValidExtension {
@@ -27,6 +33,7 @@ var validFilenameRegex = map[bool]*regexp.Regexp{
 	false: regexp.MustCompile(`^package_(.+_)+index.json$`),
 }
 
+// HasValidFilename returns whether the file at the given path has a valid package index filename.
 func HasValidFilename(filePath *paths.Path, officialCheckMode bool) bool {
 	regex := validFilenameRegex[officialCheckMode]
 	filename := filePath.Base()

project/platform/platform.go

@@ -1,3 +1,7 @@
+/*
+Package packageindex provides functions specific to checking Arduino boards platforms.
+See: https://arduino.github.io/arduino-cli/latest/platform-specification/
+*/
 package platform
 
 import (
@@ -14,6 +18,7 @@ var configurationFilenames = map[string]struct{}{
 	"programmers.txt":    empty,
 }
 
+// IsConfigurationFile returns whether the file at the given path has a boards platform configuration file filename.
 func IsConfigurationFile(filePath *paths.Path) bool {
 	_, isConfigurationFile := configurationFilenames[filePath.Base()]
 	if isConfigurationFile {
@@ -27,6 +32,7 @@ var requiredConfigurationFilenames = map[string]struct{}{
 	"boards.txt": empty,
 }
 
+// IsRequiredConfigurationFile returns whether the file at the given path has the filename of a required boards platform configuration file.
 func IsRequiredConfigurationFile(filePath *paths.Path) bool {
 	_, isRequiredConfigurationFile := requiredConfigurationFilenames[filePath.Base()]
 	if isRequiredConfigurationFile {