add/fix some comments

Author: umbynos

cli/certificates/flash.go

@@ -43,7 +43,7 @@ var (
 	certificatePaths []string
 )
 
-// NewCommand created a new `version` command
+// NewFlashCommand creates a new `flash` command
 func NewFlashCommand() *cobra.Command {
 	command := &cobra.Command{
 		Use:   "flash",

cli/common/common.go

@@ -79,7 +79,7 @@ func GetUploadToolDir(packageIndex *packageindex.Index, board *firmwareindex.Ind
 	return uploadToolDir
 }
 
-// flashSketch is the business logic that handles the flashing procedure,
+// FlashSketch is the business logic that handles the flashing procedure,
 // it returns using a buffer the out and the err of the programmer
 func FlashSketch(board *firmwareindex.IndexBoard, sketch string, uploadToolDir *paths.Path, address string) (programmerOut, programmerErr *bytes.Buffer, err error) {
 	bootloaderPort, err := GetNewAddress(board, address)
@@ -113,7 +113,7 @@ func FlashSketch(board *firmwareindex.IndexBoard, sketch string, uploadToolDir *
 	return programmerOut, programmerErr, err
 }
 
-// getNewAddress is a function used to reset a board and put it in bootloader mode
+// GetNewAddress is a function used to reset a board and put it in bootloader mode
 // it could happen that the board is assigned to a different serial port, after the reset,
 // this fuction handles also this possibility
 func GetNewAddress(board *firmwareindex.IndexBoard, oldAddress string) (string, error) {

cli/firmware/flash.go

@@ -44,7 +44,7 @@ var (
 	retries     uint8
 )
 
-// NewCommand created a new `version` command
+// NewFlashCommand creates a new `flash` command
 func NewFlashCommand() *cobra.Command {
 	command := &cobra.Command{
 		Use:   "flash",

cli/firmware/getversion.go

@@ -37,7 +37,7 @@ import (
 	semver "go.bug.st/relaxed-semver"
 )
 
-// NewCommand created a new `version` command
+// NewGetVersionCommand creates a new `get-version` command
 func NewGetVersionCommand() *cobra.Command {
 
 	command := &cobra.Command{

flasher/flasher.go

@@ -62,6 +62,7 @@ type Flasher interface {
 	sendCommand(data CommandData) error
 }
 
+// OpenSerial opens a new serial connection with the specified portAddress
 func OpenSerial(portAddress string, baudRate int, readTimeout int) (serial.Port, error) {
 
 	port, err := serial.Open(portAddress, &serial.Mode{BaudRate: baudRate})
@@ -78,12 +79,14 @@ func OpenSerial(portAddress string, baudRate int, readTimeout int) (serial.Port,
 	return port, nil
 }
 
+// FlashResult contains the result of the flashing procedure
 type FlashResult struct {
 	Programmer *ExecOutput `json:"programmer"`
 	Flasher    *ExecOutput `json:"flasher,omitempty"`
 	Version    string      `json:"version,omitempty"`
 }
 
+// ExecOutput contais the stdout and stderr output, they are used to store the output of the flashing and upload
 type ExecOutput struct {
 	Stdout string `json:"stdout"`
 	Stderr string `json:"stderr"`

indexes/download/download.go

@@ -43,6 +43,7 @@ import (
 	"go.bug.st/downloader/v2"
 )
 
+// DownloadTool downloads and returns the path on the local filesystem of a tool
 func DownloadTool(toolRelease *cores.ToolRelease) (*paths.Path, error) {
 	resource := toolRelease.GetCompatibleFlavour()
 	installDir := globals.FwUploaderPath.Join(
@@ -73,6 +74,7 @@ func DownloadTool(toolRelease *cores.ToolRelease) (*paths.Path, error) {
 	return installDir, nil
 }
 
+// DownloadFirmware downloads and returns the path on the local filesystem of a firmware
 func DownloadFirmware(firmware *firmwareindex.IndexFirmware) (*paths.Path, error) {
 	firmwarePath := globals.FwUploaderPath.Join(
 		"firmwares",
@@ -105,6 +107,7 @@ func DownloadFirmware(firmware *firmwareindex.IndexFirmware) (*paths.Path, error
 	return firmwarePath, nil
 }
 
+// DownloadSketch downloads and returns the path on the local filesystem of a sketch
 func DownloadSketch(loader *firmwareindex.IndexSketch) (*paths.Path, error) {
 	sketchPath := globals.FwUploaderPath.Join(
 		"sketch",
@@ -151,7 +154,7 @@ func Download(d *downloader.Downloader) error {
 	return nil
 }
 
-// taken and adapted from https://github.com/arduino/arduino-cli/blob/59b6277a4d6731a1c1579d43aef6df2a46a771d5/arduino/resources/checksums.go
+// VerifyFileChecksum is taken and adapted from https://github.com/arduino/arduino-cli/blob/59b6277a4d6731a1c1579d43aef6df2a46a771d5/arduino/resources/checksums.go
 func VerifyFileChecksum(checksum string, filePath *paths.Path) error {
 	if checksum == "" {
 		return fmt.Errorf("missing checksum for: %s", filePath)
@@ -193,7 +196,7 @@ func VerifyFileChecksum(checksum string, filePath *paths.Path) error {
 	return nil
 }
 
-// taken and adapted from https://github.com/arduino/arduino-cli/blob/59b6277a4d6731a1c1579d43aef6df2a46a771d5/arduino/resources/checksums.go
+// VerifyFileSize is taken and adapted from https://github.com/arduino/arduino-cli/blob/59b6277a4d6731a1c1579d43aef6df2a46a771d5/arduino/resources/checksums.go
 func VerifyFileSize(size int64, filePath *paths.Path) error {
 	info, err := filePath.Stat()
 	if err != nil {
@@ -290,6 +293,7 @@ func verifyIndex(indexPath *paths.Path, URL *url.URL) error {
 	return nil
 }
 
+// verifyPackageIndex verify if the signature is valid for the provided package index
 func verifyPackageIndex(indexPath, signaturePath *paths.Path) (bool, error) {
 	valid, _, err := security.VerifyArduinoDetachedSignature(indexPath, signaturePath)
 	if err != nil {
@@ -302,6 +306,7 @@ func verifyPackageIndex(indexPath, signaturePath *paths.Path) (bool, error) {
 	return valid, nil
 }
 
+// verifyModuleFirmwareIndex verify if the signature is valid for the provided module firmware index
 func verifyModuleFirmwareIndex(indexPath, signaturePath *paths.Path) (bool, error) {
 	keysBox, err := rice.FindBox("gpg_keys")
 	if err != nil {

indexes/firmwareindex/firmwareindex.go

@@ -36,7 +36,7 @@ type Index struct {
 	IsTrusted bool
 }
 
-// indexPackage represents a single entry from module_firmware_index.json file.
+// IndexBoard represents a single entry from module_firmware_index.json file.
 type IndexBoard struct {
 	Fqbn            string                `json:"fqbn,required"`
 	Firmwares       []*IndexFirmware      `json:"firmware,required"`
@@ -51,6 +51,7 @@ type IndexBoard struct {
 	LatestFirmware  *IndexFirmware        `json:"-"`
 }
 
+// IndexUploaderCommand represents the command-line to use for different OS
 type IndexUploaderCommand struct {
 	Linux   string `json:"linux,required"`
 	Windows string `json:"windows"`
@@ -141,7 +142,7 @@ func (i *Index) GetBoard(fqbn string) *IndexBoard {
 	return nil
 }
 
-// GetLatestFirmware returns the specified IndexFirmware version for this board.
+// GetFirmware returns the specified IndexFirmware version for this board.
 // Returns nil if version is not found.
 func (b *IndexBoard) GetFirmware(version string) *IndexFirmware {
 	v := semver.ParseRelaxed(version)
@@ -153,6 +154,7 @@ func (b *IndexBoard) GetFirmware(version string) *IndexFirmware {
 	return nil
 }
 
+// GetUploaderCommand returns the command to use for the upload
 func (b *IndexBoard) GetUploaderCommand() string {
 	if runtime.GOOS == "windows" && b.UploaderCommand.Windows != "" {
 		return b.UploaderCommand.Linux

version/version.go

@@ -26,7 +26,8 @@ var (
 	versionString        = ""
 	commit               = ""
 	date                 = ""
-	VersionInfo          *info
+	// VersionInfo contains info regarding the version
+	VersionInfo *info
 )
 
 type info struct {