Add docs for pkgs

Author: matteosuppo

v2/pkgs/indexes.go

@@ -13,11 +13,15 @@ import (
 	"go.bug.st/downloader"
 )
 
+// Indexes is a client that implements github.com/arduino/arduino-create-agent/gen/indexes.Service interface
 type Indexes struct {
 	Log    *logrus.Logger
 	Folder string
 }
 
+// Add downloads the index file found at the url contained in the payload, and saves it in the Indexes Folder.
+// If called with an already existing index, it overwrites the file.
+// It can fail if the payload is not defined, if it contains an invalid url.
 func (c *Indexes) Add(ctx context.Context, payload *indexes.IndexPayload) error {
 	// Parse url
 	indexURL, err := url.Parse(payload.URL)
@@ -46,6 +50,7 @@ func (c *Indexes) Add(ctx context.Context, payload *indexes.IndexPayload) error
 	return nil
 }
 
+// Get reads the index file from the Indexes Folder, unmarshaling it
 func (c *Indexes) Get(ctx context.Context, uri string) (index Index, err error) {
 	filename := url.PathEscape(uri)
 	path := filepath.Join(c.Folder, filename)
@@ -62,6 +67,7 @@ func (c *Indexes) Get(ctx context.Context, uri string) (index Index, err error)
 	return index, nil
 }
 
+// List reads from the Indexes Folder and returns the indexes that have been downloaded
 func (c *Indexes) List(context.Context) ([]string, error) {
 	// Read files
 	files, err := ioutil.ReadDir(c.Folder)
@@ -81,6 +87,7 @@ func (c *Indexes) List(context.Context) ([]string, error) {
 	return res, nil
 }
 
+// Remove deletes the index file from the Indexes Folder
 func (c *Indexes) Remove(ctx context.Context, payload *indexes.IndexPayload) error {
 	filename := url.PathEscape(payload.URL)
 	return os.RemoveAll(filepath.Join(c.Folder, filename))

v2/pkgs/pkgs.go

@@ -1,26 +1,29 @@
+// Package pkgs implements the functions from
+// github.com/arduino-create-agent/gen/indexes
+// and github.com/arduino-create-agent/gen/tools.
+//
+// It allows to manage package indexes from arduino
+// cores, and to download tools used for upload.
 package pkgs
 
+// Index is the go representation of a typical
+// package-index file, stripped from every non-used field.
 type Index struct {
 	Packages []struct {
-		Name       string `json:"name"`
-		Maintainer string `json:"maintainer"`
-		WebsiteURL string `json:"websiteURL"`
-		Email      string `json:"email,omitempty"`
-		Help       struct {
-			Online string `json:"online"`
-		} `json:"help,omitempty"`
+		Name  string `json:"name"`
 		Tools []Tool `json:"tools"`
 	} `json:"packages"`
 }
 
+// Tool is the go representation of the info about a
+//tool contained in a package-index file, stripped from
+//every non-used field.
 type Tool struct {
 	Name    string `json:"name"`
 	Version string `json:"version"`
 	Systems []struct {
-		Host            string `json:"host"`
-		URL             string `json:"url"`
-		ArchiveFileName string `json:"archiveFileName"`
-		Checksum        string `json:"checksum"`
-		Size            string `json:"size"`
+		Host     string `json:"host"`
+		URL      string `json:"url"`
+		Checksum string `json:"checksum"`
 	} `json:"systems"`
 }

v2/pkgs/tools.go

@@ -17,19 +17,29 @@ import (
 
 	"github.com/arduino/arduino-create-agent/gen/tools"
 	"github.com/codeclysm/extract"
-	"github.com/sirupsen/logrus"
 	"github.com/xrash/smetrics"
 )
 
+// Tools is a client that implements github.com/arduino/arduino-create-agent/gen/tools.Service interface.
+// It saves tools in a specified folder with this structure: packager/name/version
+// For example:
+//   folder
+//   └── arduino
+//       └── bossac
+//           ├── 1.6.1-arduino
+//           │   └── bossac
+//           └── 1.7.0
+//               └── bossac
+// It requires an Indexes client to list and read package index files: use the Indexes struct
 type Tools struct {
-	Log     *logrus.Logger
 	Indexes interface {
 		List(context.Context) ([]string, error)
 		Get(context.Context, string) (Index, error)
 	}
 	Folder string
 }
 
+// Available crawles the downloaded package index files and returns a list of tools that can be installed.
 func (c *Tools) Available(ctx context.Context) (res tools.ToolCollection, err error) {
 	list, err := c.Indexes.List(ctx)
 	if err != nil {
@@ -56,6 +66,7 @@ func (c *Tools) Available(ctx context.Context) (res tools.ToolCollection, err er
 	return res, nil
 }
 
+// Installed crawles the Tools Folder and finds the installed tools.
 func (c *Tools) Installed(ctx context.Context) (tools.ToolCollection, error) {
 	res := tools.ToolCollection{}
 
@@ -94,6 +105,8 @@ func (c *Tools) Installed(ctx context.Context) (tools.ToolCollection, error) {
 	return res, nil
 }
 
+// Install crawles the Index folder, downloads the specified tool, extracts the archive in the Tools Folder.
+// It checks for the Signature specified in the package index.
 func (c *Tools) Install(ctx context.Context, payload *tools.ToolPayload) error {
 	list, err := c.Indexes.List(ctx)
 	if err != nil {
@@ -157,6 +170,7 @@ func (c *Tools) install(ctx context.Context, packager string, tool Tool) error {
 	return nil
 }
 
+// Remove deletes the tool folder from Tools Folder
 func (c *Tools) Remove(ctx context.Context, payload *tools.ToolPayload) error {
 	path := filepath.Join(payload.Packager, payload.Name, payload.Version)