(f) add doc comments

data-generator/internal/command/command.go

@@ -1,3 +1,4 @@
+// Package command implements the data-generator commands.
 package command
 
 import (
@@ -7,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DataGenerator is the `data-generator` root command.
 func DataGenerator(rootCommand *cobra.Command, cliArguments []string) {
 	registryPath, err := rootCommand.Flags().GetString("registry")
 	if err != nil {

data-generator/internal/data/data.go

@@ -1,3 +1,4 @@
+// Package data works with the generated data.
 package data
 
 import (
@@ -11,120 +12,135 @@ import (
 	"github.com/per1234/inoplatforms/data-generator/internal/packageindex"
 )
 
+// RepositoryType is the type for source repository data.
 type RepositoryType struct {
-	Url  string
-	Ref  string
-	Path string
+	Url  string // Url is the repository URL.
+	Ref  string // Ref is the Git ref (e.g., branch name) in the repository.
+	Path string // Path is the path of the source under the repository.
 }
+
+// SourceType is the type for source data.
 type SourceType struct {
-	Repository RepositoryType
+	Repository RepositoryType // Repository is data about the source repository.
 }
 
+// ToolDependencyType is the type for tool dependency data.
 type ToolDependencyType struct {
-	Packager          string
-	Name              string
-	Version           string
-	PackageProviderID string
+	Packager          string // Packager is the machine identifier of the tool dependency's package.
+	Name              string // Name is the machine identifier of the tool dependency.
+	Version           string // Version is the version number of the tool dependency.
+	PackageProviderID string // PackageProviderID is the ID number of the tool dependency's package provider.
 }
 
+// PlatformType is the type for platform data.
 type PlatformType struct {
-	Name                   string
-	Architecture           string
-	Help                   string
-	Boards                 []BoardType
-	Source                 SourceType
-	InstallationReferences []string
-	ToolsDependencies      []ToolDependencyType
-	DiscoveryDependencies  []ToolType
-	MonitorDependencies    []ToolType
-	Releases               []PlatformReleaseType
+	Name                   string                // Name is the human identifier for the latest release of the platform.
+	Architecture           string                // Architecture is the machine identifier for the platform.
+	Deprecated             bool                  // Deprecated indicates whether the platform is deprecated.
+	Help                   string                // Help contains data about user support for the platform.
+	Boards                 []BoardType           // Boards contains data about the boards supported by the latest release of the platform.
+	Source                 SourceType            // Source contains data about the platform source code.
+	InstallationReferences []string              // InstallationReferences contains links to platform installation documentation.
+	ToolsDependencies      []ToolDependencyType  // ToolsDependencies is the standard tool dependencies of the latest release of the platform.
+	DiscoveryDependencies  []ToolType            // DiscoveryDependencies is the pluggable discovery tool dependencies of latest release of the platform.
+	MonitorDependencies    []ToolType            // MonitorDependencies is the pluggable monitor tool dependencies of the latest release of the platform.
+	Releases               []PlatformReleaseType // Releases contains data about each of the releases of the platform.
 	// TODO: SearchData SearchDataType
 }
 
 // TODO:
+// // SearchDataType is the type for site search index data.
 // type SearchDataType struct{
 // Ref string
 // SearchContent string
 // }
 
+// BoardType is the type for data about a board supported by the platform.
 type BoardType struct {
-	Name string
+	Name string // Name is the human identifier for the board.
 }
 
+// PlatformReleaseType is the type for platform release data.
 type PlatformReleaseType struct {
-	Name                  string
-	Version               string
-	Help                  string
-	ArchiveURL            string
-	Checksum              string
-	Boards                []BoardType
-	ToolsDependencies     []ToolDependencyType
-	DiscoveryDependencies []ToolType
-	MonitorDependencies   []ToolType
-}
-
+	Name                  string               // Name is the human identifier for the platform.
+	Version               string               // Version is the platform release version number.
+	Help                  string               // Help contains data about user support for the platform release.
+	ArchiveUrl            string               // ArchiveUrl is the platform release archive download URL.
+	Checksum              string               // Checksum is the platform release archive checksum.
+	Boards                []BoardType          // Boards contains data about the boards supported by the platform release.
+	ToolsDependencies     []ToolDependencyType // ToolsDependencies is the standard tool dependencies of the platform release.
+	DiscoveryDependencies []ToolType           // DiscoveryDependencies is the pluggable discovery tool dependencies of the platform release.
+	MonitorDependencies   []ToolType           // MonitorDependencies is the pluggable monitor tool dependencies of the platform release.
+}
+
+// SystemType is the type for host-specific tool release data.
 type SystemType struct {
-	Checksum   string
-	Host       string
-	ArchiveURL string
+	Checksum   string // Checksum is the tool release archive checksum.
+	Host       string // Host is the host architecture machine identifier.
+	ArchiveUrl string // ArchiveUrl is the tool release archive download URL.
 }
 
+// ToolType is the type for tool data.
 type ToolType struct {
-	Name     string
-	Source   SourceType
-	Releases []ToolReleaseType
-	// TODO: SearchData SearchDataType
+	Name     string            // Name is the machine identifier for the tool.
+	Source   SourceType        // Source contains data about the tool source code.
+	Releases []ToolReleaseType // Releases contains data about each of the releases of the tool.
+	// TODO: SearchData SearchDataType	// SearchData contains site search index data for the tool.
 }
 
 type ToolReleaseType struct {
-	Version string
-	Systems []SystemType
+	Version string       // Version is the tool release version.
+	Systems []SystemType // Systems contains target host-specific data.
 }
 
 type PackageType struct {
-	Name       string
-	Maintainer string
-	WebsiteURL string
-	Platforms  []PlatformType
-	Tools      []ToolType
+	Name       string         // Name is the machine identifier of the package.
+	Maintainer string         // Maintainer is the human identifier for the maintainer of the package.
+	WebsiteUrl string         // WebsiteURL is the URL for information about the package.
+	Platforms  []PlatformType // Platforms is the platforms provided by the package.
+	Tools      []ToolType     // Tools is the tools provided by the package.
 }
 
+// PackageIndexType is the type for package index data.
 type PackageIndexType struct {
-	Url      string
-	Notes    string
-	Source   SourceType
-	Packages []PackageType
+	Url    string     // Url is the publication URL for the package index.
+	Notes  string     // Notes is notes about the package index.
+	Source SourceType // Source is data about the package index source.
 }
 
+// PackageProviderType is the type for package provider data.
 type PackageProviderType struct {
-	Id           string
-	PackageIndex PackageIndexType
-	Packages     []PackageType
-	Status       StatusType
+	Id           string           // Id is an arbitrary unique ID number for the package provider.
+	PackageIndex PackageIndexType // PackageIndex is data about the package index that provides the packages.
+	Packages     []PackageType    // Packages is the list of provided packages.
+	Status       StatusType       // Status contains data about the status of the collected data for the package provider.
 }
 
-// StatusType is the type for metadata about the status of the data.
+// StatusType is the type for metadata about the status of the collected data.
 type StatusType struct {
-	Result  ResultType
-	Message string
+	Result  ResultType // Result is the data collection result.
+	Message string     // Message is a message for humans about the status of the collected data.
 }
 
+// ResultType is the type for the data collection result.
 type ResultType int
 
 const (
-	Success ResultType = iota
-	Failure
+	Success ResultType = iota // Success indicates data collection was successful.
+	Failure                   // Failure indicates data collection failed.
 )
 
+// Type is the type for data.
 type Type struct {
-	PackageProviders []PackageProviderType
-	Stats            StatsType
+	PackageProviders []PackageProviderType // PackageProviders is the list of providers of packages.
+	Stats            StatsType             // Stats is statistics about the data overall.
 }
 
+// StatsType is the type for data statistics.
 type StatsType struct {
-	PlatformCount     int
-	ArchitectureCount int
-	Timestamp         string
+	PlatformCount     int    // PlatformCount is the number of platforms.
+	ArchitectureCount int    // ArchitectureCount is the number of unique architectures.
+	Timestamp         string // Timestamp is the timestamp of when the data was generated.
 }
 
 // Populate gathers all additional data.

data-generator/internal/packageindex/packageindex.go

@@ -12,111 +12,87 @@ import (
 	"golang.org/x/exp/slog"
 )
 
+// Type is the type for package index data.
 type Type struct {
-	Packages []*Package `json:"packages"`
+	Packages []*PackageType // Packages is the packages of the package index.
 }
 
-// indexPackage represents a single entry from package_index.json file.
-//
-//easyjson:json
-type Package struct {
-	Name       string             `json:"name"`
-	Maintainer string             `json:"maintainer"`
-	WebsiteURL string             `json:"websiteUrl"`
-	URL        string             `json:"Url"`
-	Email      string             `json:"email"`
-	Platforms  []*PlatformRelease `json:"platforms"`
-	Tools      []*ToolRelease     `json:"tools"`
-	Help       Help               `json:"help,omitempty"`
+// PackageType is the type for package data.
+type PackageType struct {
+	Name       string                 // Name is the machine identifier of the package.
+	Maintainer string                 // Maintainer is the human identifier for the maintainer of the package.
+	WebsiteURL string                 // WebsiteURL is the URL for information about the package.
+	URL        string                 // URL is the URL for information about the package.
+	Email      string                 // Email is the email address to contact the package maintainer.
+	Platforms  []*PlatformReleaseType // Platforms is the platform releases provided by the package.
+	Tools      []*ToolReleaseType     // Tools is the tool releases provided by the package.
+	Help       HelpType               // Help contains data about user support for the package.
 }
 
-// PlatformRelease represents a single Core Platform from package_index.json file.
-//
-//easyjson:json
-type PlatformRelease struct {
-	Name                  string                `json:"name"`
-	Architecture          string                `json:"architecture"`
-	Version               *semver.Version       `json:"version"`
-	Deprecated            bool                  `json:"deprecated"`
-	Category              string                `json:"category"`
-	URL                   string                `json:"url"`
-	ArchiveFileName       string                `json:"archiveFileName"`
-	Checksum              string                `json:"checksum"`
-	Size                  json.Number           `json:"size"`
-	Boards                []Board               `json:"boards"`
-	Help                  Help                  `json:"help,omitempty"`
-	ToolDependencies      []ToolDependency      `json:"toolsDependencies"`
-	DiscoveryDependencies []DiscoveryDependency `json:"discoveryDependencies"`
-	MonitorDependencies   []MonitorDependency   `json:"monitorDependencies"`
+// PlatformReleaseType is the type for platform release data.
+type PlatformReleaseType struct {
+	Name                  string                           // Name is the human identifier for the platform.
+	Architecture          string                           // Architecture is the machine identifier for the platform.
+	Version               *semver.Version                  // Version is the platform release version number.
+	Deprecated            bool                             // Deprecated indicates whether the platform is deprecated.
+	Category              string                           // Category is the platform's category.
+	URL                   string                           // URL is the platform release archive download URL.
+	ArchiveFileName       string                           // ArchiveFileName is the platform release archive filename.
+	Checksum              string                           // Checksum is the platform release archive checksum.
+	Size                  json.Number                      // Size is the platform release archive file size.
+	Boards                []BoardType                      // Boards contains data about the boards supported by the platform release.
+	Help                  HelpType                         // Help contains data about user support for the platform release.
+	ToolsDependencies     []VersionedToolDependencyType    // ToolsDependencies is the standard tool dependencies of the platform release.
+	DiscoveryDependencies []NonVersionedToolDependencyType // DiscoveryDependencies is the pluggable discovery tool dependencies of the platform release.
+	MonitorDependencies   []NonVersionedToolDependencyType // MonitorDependencies is the pluggable monitor tool dependencies of the platform release.
 }
 
-// indexToolDependency represents a single dependency of a core from a tool.
-//
-//easyjson:json
-type ToolDependency struct {
-	Packager string                 `json:"packager"`
-	Name     string                 `json:"name"`
-	Version  *semver.RelaxedVersion `json:"version"`
+// NonVersionedToolDependencyType is the type for versioned tool dependency data.
+type VersionedToolDependencyType struct {
+	Packager string
+	Name     string
+	Version  *semver.RelaxedVersion
 }
 
-// indexDiscoveryDependency represents a single dependency of a core from a pluggable discovery tool.
-//
-//easyjson:json
-type DiscoveryDependency struct {
-	Packager string `json:"packager"`
-	Name     string `json:"name"`
+// NonVersionedToolDependencyType is the type for non-versioned tool dependency data.
+type NonVersionedToolDependencyType struct {
+	Packager string // Packager is the vendor name of the tool.
+	Name     string // Name is the name of the tool.
 }
 
-// indexMonitorDependency represents a single dependency of a core from a pluggable monitor tool.
-//
-//easyjson:json
-type MonitorDependency struct {
-	Packager string `json:"packager"`
-	Name     string `json:"name"`
+// ToolReleaseType is the type for tool release data.
+type ToolReleaseType struct {
+	Name    string                   // Name is the machine identifier for the tool.
+	Version *semver.RelaxedVersion   // Version is the tool release version.
+	Systems []ToolReleaseFlavourType // Systems contains target host-specific data.
 }
 
-// indexToolRelease represents a single Tool from package_index.json file.
-//
-//easyjson:json
-type ToolRelease struct {
-	Name    string                 `json:"name"`
-	Version *semver.RelaxedVersion `json:"version"`
-	Systems []ToolReleaseFlavour   `json:"systems"`
+// ToolReleaseFlavourType is the type for host-specific tool release data.
+type ToolReleaseFlavourType struct {
+	OS              string      // OS is the host architecture machine identifier.
+	URL             string      // URL is the tool release archive download URL.
+	ArchiveFileName string      // ArchiveFileName is the tool release archive filename.
+	Size            json.Number // Size is the tool release archive file size.
+	Checksum        string      // Checksum is the tool release archive checksum.
 }
 
-// indexToolReleaseFlavour represents a single tool flavor in the package_index.json file.
-//
-//easyjson:json
-type ToolReleaseFlavour struct {
-	OS              string      `json:"host"`
-	URL             string      `json:"url"`
-	ArchiveFileName string      `json:"archiveFileName"`
-	Size            json.Number `json:"size"`
-	Checksum        string      `json:"checksum"`
+// BoardType is the type for data about a board supported by the platform.
+type BoardType struct {
+	Name string        // Name is the human identifier for the board.
+	ID   []BoardIDType // ID contains identification data for the board.
 }
 
-// indexBoard represents a single Board as written in package_index.json file.
-//
-//easyjson:json
-type Board struct {
-	Name string    `json:"name"`
-	ID   []BoardID `json:"id,omitempty"`
+// BoardIDType is the type for board identification data.
+type BoardIDType struct {
+	USB string // USB is the USB identification for the board.
 }
 
-// indexBoardID represents the ID of a single board. i.e. uno, yun, diecimila, micro and the likes
-//
-//easyjson:json
-type BoardID struct {
-	USB string `json:"usb"`
-}
-
-// indexHelp represents the help URL
-//
-//easyjson:json
-type Help struct {
-	Online string `json:"online,omitempty"`
+// HelpType is the type for user support request data.
+type HelpType struct {
+	Online string // Online is the online support request URL.
 }
 
+// Get downloads and parses a package index.
 func Get(url string) (Type, error) {
 	// Download the index.
 	httpResponse, err := http.Get(url)