Add missing doc comments

Author: per1234

libraries/bad_file_cleaner.go

@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 )
 
+// FailIfHasUndesiredFiles returns an error if the folder contains any undesired files.
 func FailIfHasUndesiredFiles(folder string) error {
 	err := failIfContainsForbiddenFileInRoot(folder)
 	if err != nil {
@@ -15,6 +16,7 @@ func FailIfHasUndesiredFiles(folder string) error {
 	return failIfContainsExes(folder)
 }
 
+// ForbiddenFiles is the names of the forbidden files.
 var ForbiddenFiles = []string{".development"}
 
 func failIfContainsForbiddenFileInRoot(folder string) error {
@@ -27,6 +29,7 @@ func failIfContainsForbiddenFileInRoot(folder string) error {
 	return nil
 }
 
+// Patterns is the file patterns of executables.
 var Patterns = []string{"*.exe"}
 
 func failIfContainsExes(folder string) error {

libraries/clamav.go

@@ -31,6 +31,7 @@ func modifyEnv(env []string, key, value string) []string {
 	return envMapToSlice(envMap)
 }
 
+// RunAntiVirus scans the folder for viruses.
 func RunAntiVirus(folder string) ([]byte, error) {
 	cmd := exec.Command("clamdscan", "-i", folder)
 	cmd.Env = modifyEnv(os.Environ(), "LANG", "en")

libraries/cron/fill_missing_checksums.go

@@ -8,8 +8,8 @@ import (
 )
 
 /*
-   Check for missing size and checksum field and fills them
-   by downloading a copy of the file.
+FillMissingChecksumsForDownloadArchives checks for missing size and checksum field and fills them
+by downloading a copy of the file.
 */
 func FillMissingChecksumsForDownloadArchives(URL string, filename string) (int64, string, error) {
 	size, err := download(URL, filename)

libraries/db/db.go

@@ -55,10 +55,12 @@ type Dependency struct {
 	Version string
 }
 
+// New returns a new DB object.
 func New(libraryFile string) *DB {
 	return &DB{libraryFile: libraryFile}
 }
 
+// AddLibrary adds a library to the database.
 func (db *DB) AddLibrary(library *Library) error {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -70,6 +72,7 @@ func (db *DB) AddLibrary(library *Library) error {
 	return nil
 }
 
+// HasLibrary returns whether the database already contains the given library.
 func (db *DB) HasLibrary(libraryName string) bool {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -81,6 +84,7 @@ func (db *DB) hasLibrary(libraryName string) bool {
 	return found != nil
 }
 
+// FindLibrary returns the Library object for the given name.
 func (db *DB) FindLibrary(libraryName string) (*Library, error) {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -96,6 +100,7 @@ func (db *DB) findLibrary(libraryName string) (*Library, error) {
 	return nil, errors.New("library not found")
 }
 
+// AddRelease adds a library release to the database.
 func (db *DB) AddRelease(release *Release, repoURL string) error {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -120,6 +125,7 @@ func (db *DB) AddRelease(release *Release, repoURL string) error {
 	return nil
 }
 
+// HasReleaseByNameVersion returns whether the database contains a release for the given library and version number.
 func (db *DB) HasReleaseByNameVersion(libraryName string, libraryVersion string) bool {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -131,6 +137,7 @@ func (db *DB) hasReleaseByNameVersion(libraryName string, libraryVersion string)
 	return found != nil
 }
 
+// HasRelease returns whether the database already contains the given Release object.
 func (db *DB) HasRelease(release *Release) bool {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -141,6 +148,7 @@ func (db *DB) hasRelease(release *Release) bool {
 	return db.hasReleaseByNameVersion(release.LibraryName, release.Version.String())
 }
 
+// FindRelease returns the Release object from the database that matches the given object.
 func (db *DB) FindRelease(release *Release) (*Release, error) {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -156,6 +164,7 @@ func (db *DB) findReleaseByNameVersion(libraryName string, libraryVersion string
 	return nil, errors.New("library not found")
 }
 
+// LoadFromFile returns a DB object loaded from the given filename.
 func LoadFromFile(filename string) (*DB, error) {
 	file, err := os.Open(filename)
 	if err != nil {
@@ -170,6 +179,7 @@ func LoadFromFile(filename string) (*DB, error) {
 	return db, nil
 }
 
+// Load returns a DB object loaded from the given reader.
 func Load(r io.Reader) (*DB, error) {
 	decoder := json.NewDecoder(r)
 	db := new(DB)
@@ -180,6 +190,7 @@ func Load(r io.Reader) (*DB, error) {
 	return db, nil
 }
 
+// SaveToFile saves the database to a file.
 func (db *DB) SaveToFile() error {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -191,6 +202,7 @@ func (db *DB) SaveToFile() error {
 	return db.save(file)
 }
 
+// Save writes the database via the given writer.
 func (db *DB) Save(r io.Writer) error {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -222,6 +234,7 @@ func (db *DB) findLatestReleaseOfLibrary(lib *Library) (*Release, error) {
 	return found, nil
 }
 
+// FindReleasesOfLibrary returns the database's releases for the given Library object.
 func (db *DB) FindReleasesOfLibrary(lib *Library) []*Release {
 	db.mutex.Lock()
 	defer db.mutex.Unlock()
@@ -239,10 +252,12 @@ func (db *DB) findReleasesOfLibrary(lib *Library) []*Release {
 	return releases
 }
 
+// Commit saves the database to disk.
 func (db *DB) Commit() error {
 	return db.SaveToFile()
 }
 
+// Init loads a database from file and returns it.
 func Init(libraryFile string) *DB {
 	libs, err := LoadFromFile(libraryFile)
 	if err != nil {

libraries/db/versioning.go

@@ -2,28 +2,34 @@ package db
 
 import "encoding/json"
 
+// Version is the type for library versions.
 type Version struct {
 	version string
 }
 
+// Less returns whether the receiver version is lower than the argument.
 func (version *Version) Less(other Version) (bool, error) {
 	// TODO: apply semantic versioning
 	return version.version < other.version, nil
 }
 
+// String returns the version in string form.
 func (version *Version) String() string {
 	return version.version
 }
 
+// UnmarshalJSON parses the JSON-encoded argument and stores the result in the receiver.
 func (version *Version) UnmarshalJSON(data []byte) error {
 	return json.Unmarshal(data, &version.version)
 }
 
+// MarshalJSON returns the JSON encoding of the receiver.
 func (version *Version) MarshalJSON() ([]byte, error) {
 	// Encode version as a string
 	return json.Marshal(version.version)
 }
 
+// VersionFromString parses a string to a Version object.
 func VersionFromString(str string) Version {
 	return Version{version: str}
 }

libraries/file/SCCS.go

@@ -1,5 +1,6 @@
 package file
 
+// SCCSFiles is a map of folder names used internally by source code control systems.
 var SCCSFiles = map[string]bool{
 	"CVS":  true,
 	"RCS":  true,
@@ -8,6 +9,7 @@ var SCCSFiles = map[string]bool{
 	".hg":  true,
 	".bzr": true}
 
+// IsSCCS returns whether the given string is a folder name used internally by source code control systems.
 func IsSCCS(name string) bool {
 	return SCCSFiles[name]
 }

libraries/github_release_downloader.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 )
 
+// GithubDownloadRelease downloads GitHub's archive of the release.
 func GithubDownloadRelease(repoURL, version string) (string, int64, string, error) {
 	tempfile, err := ioutil.TempFile("", "github")
 	if err != nil {

libraries/hash/checksumhelper.go

@@ -7,7 +7,7 @@ import (
 	"os"
 )
 
-// Calculate hash for the file
+// Checksum calculates the hash for the file.
 func Checksum(filename string) (string, error) {
 	hasher := sha256.New()
 	file, err := os.Open(filename)

libraries/repoarchive.go

@@ -9,6 +9,7 @@ import (
 	"arduino.cc/repository/libraries/zip"
 )
 
+// ZipRepo creates a ZIP archive of the repo folder and returns its path.
 func ZipRepo(repoFolder string, baseFolder string, zipFolderName string) (string, error) {
 	err := os.MkdirAll(baseFolder, os.FileMode(0755))
 	if err != nil {
@@ -23,6 +24,7 @@ func ZipRepo(repoFolder string, baseFolder string, zipFolderName string) (string
 	return absoluteFileName, nil
 }
 
+// ZipFolderName returns the name to use for the folder.
 func ZipFolderName(library *metadata.LibraryMetadata) string {
 	pattern := regexp.MustCompile("[^a-zA-Z0-9]")
 	return pattern.ReplaceAllString(library.Name, "_") + "-" + library.Version

libraries/repoclone.go

@@ -22,6 +22,7 @@ type Repository struct {
 	URL        string
 }
 
+// CloneOrFetch returns a Repository object. If the repository is already present, it is opened. Otherwise, cloned.
 func CloneOrFetch(repoMeta *Repo, folderName string) (*Repository, error) {
 	repo := Repository{
 		FolderPath: folderName,
@@ -64,6 +65,7 @@ func CloneOrFetch(repoMeta *Repo, folderName string) (*Repository, error) {
 	return &repo, err
 }
 
+// GenerateLibraryFromRepo parses a repository and returns the library metadata.
 func GenerateLibraryFromRepo(repo *Repository) (*metadata.LibraryMetadata, error) {
 	bytes, err := ioutil.ReadFile(filepath.Join(repo.FolderPath, "library.properties"))
 	if err != nil {
@@ -88,6 +90,7 @@ func GenerateLibraryFromRepo(repo *Repository) (*metadata.LibraryMetadata, error
 	return library, nil
 }
 
+// UpdateLibrary adds a release to the library database.
 func UpdateLibrary(release *db.Release, repoURL string, libraryDb *db.DB) error {
 	var err error
 

libraries/repolist.go

@@ -64,10 +64,12 @@ func (_ repoMatcherIfGithub) Match(r string) bool {
 }
 */
 
+// GitURLsError is the type for the unknown or unsupported repositories data.
 type GitURLsError struct {
 	Repos []*Repo
 }
 
+// Repo is the type for the library repository data.
 type Repo struct {
 	URL         string
 	Types       []string
@@ -87,6 +89,7 @@ func (repo *Repo) AsFolder() (string, error) {
 	return folderName, nil
 }
 
+// ReposByURL is the type for the libraries repository data.
 type ReposByURL []*Repo
 
 func (r ReposByURL) Len() int {
@@ -180,6 +183,7 @@ func toListOfUniqueRepos(repos []*Repo) []*Repo {
 	return finalRepos
 }
 
+// ListRepos loads a list from the given filename.
 func ListRepos(reposFilename string) ([]*Repo, error) {
 	repos, err := loadRepoListFromFile(reposFilename)
 	if err != nil {

libraries/zip/ziphelper.go

@@ -10,7 +10,7 @@ import (
 	"arduino.cc/repository/libraries/file"
 )
 
-// ZipDirectory creates a new zip archive that contains a copy of "rootFolder" into "zipFile".
+// Directory creates a new zip archive that contains a copy of "rootFolder" into "zipFile".
 // Inside the archive "rootFolder" will be renamed to "zipRootFolderName".
 func Directory(rootFolder string, zipRootFolderName string, zipFile string) error {
 	checks := func(path string, info os.FileInfo, err error) error {

sync_libraries.go

@@ -17,6 +17,7 @@ import (
 	"github.com/go-git/go-git/v5/plumbing"
 )
 
+// Config is the type of the engine configuration.
 type Config struct {
 	BaseDownloadURL string
 	LibrariesFolder string