chore: driver godoc

Adds or updates the Go Doc comments for the driver functions.

Signed-off-by: Ryan Johnson <ryan@tenthirtyam.org>

Author: tenthirtyam

builder/vsphere/driver/cluster.go

@@ -10,6 +10,9 @@ type Cluster struct {
 	cluster *object.ClusterComputeResource
 }
 
+// FindCluster locates a cluster within the vCenter environment by its name.
+// Returns a Cluster object or an error if not found or if the retrieval
+// process fails.
 func (d *VCenterDriver) FindCluster(name string) (*Cluster, error) {
 	c, err := d.finder.ClusterComputeResource(d.ctx, name)
 	if err != nil {

builder/vsphere/driver/datastore.go

@@ -33,14 +33,16 @@ type DatastoreDriver struct {
 	driver *VCenterDriver
 }
 
+// NewDatastore creates a new Datastore object.
 func (d *VCenterDriver) NewDatastore(ref *types.ManagedObjectReference) Datastore {
 	return &DatastoreDriver{
 		ds:     object.NewDatastore(d.client.Client, *ref),
 		driver: d,
 	}
 }
 
-// If name is an empty string, then resolve host's one
+// FindDatastore locates a datastore by its name and an optional host.
+// Returns a Datastore object or an error if the datastore is not found.
 func (d *VCenterDriver) FindDatastore(name string, host string) (Datastore, error) {
 	if name == "" {
 		h, err := d.FindHost(host)
@@ -76,6 +78,9 @@ func (d *VCenterDriver) FindDatastore(name string, host string) (Datastore, erro
 	}, nil
 }
 
+// GetDatastoreName retrieves the name of a datastore by its ID.
+// Returns the name of the datastore or an error if the retrieval process
+// fails.
 func (d *VCenterDriver) GetDatastoreName(id string) (string, error) {
 	obj := types.ManagedObjectReference{
 		Type:  "Datastore",
@@ -91,6 +96,9 @@ func (d *VCenterDriver) GetDatastoreName(id string) (string, error) {
 	return me.Name, nil
 }
 
+// Info retrieves properties of the datastore object with optional filters
+// specified as parameters. If no parameters are provided, all properties are
+// returned.
 func (ds *DatastoreDriver) Info(params ...string) (*mo.Datastore, error) {
 	var p []string
 	if len(params) == 0 {
@@ -106,6 +114,7 @@ func (ds *DatastoreDriver) Info(params ...string) (*mo.Datastore, error) {
 	return &info, nil
 }
 
+// DirExists checks if a directory exists in a datastore.
 func (ds *DatastoreDriver) DirExists(filepath string) bool {
 	_, err := ds.ds.Stat(ds.driver.ctx, filepath)
 	if _, ok := err.(object.DatastoreNoSuchDirectoryError); ok {
@@ -114,24 +123,28 @@ func (ds *DatastoreDriver) DirExists(filepath string) bool {
 	return true
 }
 
+// FileExists checks if a file exists in a datastore.
 func (ds *DatastoreDriver) FileExists(path string) bool {
 	_, err := ds.ds.Stat(ds.driver.ctx, path)
 	return err == nil
 }
 
+// Name retrieves the name of a datastore.
 func (ds *DatastoreDriver) Name() string {
 	return ds.ds.Name()
 }
 
+// Reference retrieves the reference of a datastore.
 func (ds *DatastoreDriver) Reference() types.ManagedObjectReference {
 	return ds.ds.Reference()
 }
 
+// ResolvePath resolves a path in a datastore.
 func (ds *DatastoreDriver) ResolvePath(path string) string {
 	return ds.ds.Path(path)
 }
 
-// The file ID isn't available via the API, so we use DatastoreBrowser to search
+// GetDatastoreFilePath retrieves the full path of a file in a specified datastore directory by its datastore ID and name.
 func (d *VCenterDriver) GetDatastoreFilePath(datastoreID, dir, filename string) (string, error) {
 	ref := types.ManagedObjectReference{Type: "Datastore", Value: datastoreID}
 	ds := object.NewDatastore(d.vimClient, ref)
@@ -167,6 +180,8 @@ func (d *VCenterDriver) GetDatastoreFilePath(datastoreID, dir, filename string)
 	return res.File[0].GetFileInfo().Path, nil
 }
 
+// UploadFile uploads a file from the local source path to the destination path
+// in the datastore, with optional host context.
 func (ds *DatastoreDriver) UploadFile(src, dst, host string, setHost bool) error {
 	p := soap.DefaultUpload
 	ctx := ds.driver.ctx
@@ -182,6 +197,7 @@ func (ds *DatastoreDriver) UploadFile(src, dst, host string, setHost bool) error
 	return ds.ds.UploadFile(ctx, src, dst, &p)
 }
 
+// Delete deletes a file from a datastore by a path.
 func (ds *DatastoreDriver) Delete(path string) error {
 	dc, err := ds.driver.finder.Datacenter(ds.driver.ctx, ds.ds.DatacenterPath)
 	if err != nil {
@@ -191,6 +207,7 @@ func (ds *DatastoreDriver) Delete(path string) error {
 	return fm.Delete(ds.driver.ctx, path)
 }
 
+// MakeDirectory creates a directory in a datastore by a path.
 func (ds *DatastoreDriver) MakeDirectory(path string) error {
 	dc, err := ds.driver.finder.Datacenter(ds.driver.ctx, ds.ds.DatacenterPath)
 	if err != nil {
@@ -200,8 +217,7 @@ func (ds *DatastoreDriver) MakeDirectory(path string) error {
 	return fm.FileManager.MakeDirectory(ds.driver.ctx, path, dc, true)
 }
 
-// Cuts out the datastore prefix
-// Example: "[datastore1] file.ext" --> "file.ext"
+// RemoveDatastorePrefix removes the datastore prefix from a path.
 func RemoveDatastorePrefix(path string) string {
 	res := object.DatastorePath{}
 	if hadPrefix := res.FromString(path); hadPrefix {
@@ -215,6 +231,8 @@ type DatastoreIsoPath struct {
 	path string
 }
 
+// Validate checks if the path matches the expected datastore ISO path format.
+// Returns true if valid, otherwise false.
 func (d *DatastoreIsoPath) Validate() bool {
 	// Matches:
 	// [datastore] /dir/subdir/file
@@ -226,11 +244,12 @@ func (d *DatastoreIsoPath) Validate() bool {
 	return matched
 }
 
+// GetFilePath removes the datastore name from the path and returns the trimmed
+// file path portion of the datastore ISO path.
 func (d *DatastoreIsoPath) GetFilePath() string {
 	filePath := d.path
 	parts := strings.Split(d.path, "]")
 	if len(parts) > 1 {
-		// removes datastore name from path
 		filePath = parts[1]
 		filePath = strings.TrimSpace(filePath)
 	}

builder/vsphere/driver/disk.go

@@ -22,10 +22,12 @@ type StorageConfig struct {
 	Storage            []Disk
 }
 
+// AddStorageDevices adds virtual storage devices to an existing device list
+// based on the configuration. Adds a new controller for each controller type
+// specified in the configuration and adds virtual disks to the controller.
 func (c *StorageConfig) AddStorageDevices(existingDevices object.VirtualDeviceList) ([]types.BaseVirtualDeviceConfigSpec, error) {
 	newDevices := object.VirtualDeviceList{}
 
-	// Create new controller based on existing devices list and add it to the new devices list.
 	var controllers []types.BaseVirtualController
 	for _, controllerType := range c.DiskControllerType {
 		var device types.BaseVirtualDevice
@@ -71,7 +73,8 @@ func (c *StorageConfig) AddStorageDevices(existingDevices object.VirtualDeviceLi
 	return newDevices.ConfigSpec(types.VirtualDeviceConfigSpecOperationAdd)
 }
 
-// Returns the first virtual disk found in the devices list.
+// findDisk scans a list of virtual devices and retrieves a single virtual disk
+// if exactly one is found.  Returns an error if no disk or multiple disks are found.
 // TODO: Add support for multiple disks.
 func findDisk(devices object.VirtualDeviceList) (*types.VirtualDisk, error) {
 	var disks []*types.VirtualDisk
@@ -90,6 +93,6 @@ func findDisk(devices object.VirtualDeviceList) (*types.VirtualDisk, error) {
 		// Single disk found.
 		return disks[0], nil
 	}
-	// More than one disk found.
+	// Multiple disks found.
 	return nil, errors.New("more than one virtual disk found, only a single disk is allowed")
 }

builder/vsphere/driver/driver.go

@@ -134,10 +134,7 @@ func (d *VCenterDriver) Cleanup() (error, error) {
 	return d.restClient.client.Logout(d.ctx), d.client.SessionManager.Logout(d.ctx)
 }
 
-// The rest.Client requires vCenter.
-// RestClient is to modularize the rest.Client session and use it only when is necessary.
-// This will allow users without vCenter Server to use the other features that do not use the rest.Client.
-// To use the client login/logout must be done to create an authenticated session.
+// RestClient manages RESTful interactions with vCenter, handling client initialization and credential storage.
 type RestClient struct {
 	client      *rest.Client
 	credentials *url.Userinfo

builder/vsphere/driver/folder.go

@@ -26,9 +26,12 @@ func (d *VCenterDriver) NewFolder(ref *types.ManagedObjectReference) *Folder {
 	}
 }
 
+// FindFolder locates or creates a folder structure within a datastore based
+// on the provided folder name. Returns a pointer to the Folder object or an
+// error if the operation fails.
 func (d *VCenterDriver) FindFolder(name string) (*Folder, error) {
 	if name != "" {
-		// create folders if they don't exist
+		// If the folder does not exist, create it.
 		parent := ""
 		parentFolder, err := d.finder.Folder(d.ctx, path.Join(d.datacenter.InventoryPath, "vm"))
 		if err != nil {
@@ -59,6 +62,8 @@ func (d *VCenterDriver) FindFolder(name string) (*Folder, error) {
 	}, nil
 }
 
+// Info retrieves properties of the folder object with optional filters specified
+// as parameters. If no parameters are provided, all properties are returned.
 func (f *Folder) Info(params ...string) (*mo.Folder, error) {
 	var p []string
 	if len(params) == 0 {
@@ -74,6 +79,8 @@ func (f *Folder) Info(params ...string) (*mo.Folder, error) {
 	return &info, nil
 }
 
+// Path constructs and returns the full hierarchical path of the folder,
+// starting from the datacenter level or an error.
 func (f *Folder) Path() (string, error) {
 	info, err := f.Info("name", "parent")
 	if err != nil {

builder/vsphere/driver/host.go

@@ -14,13 +14,17 @@ type Host struct {
 	host   *object.HostSystem
 }
 
+// NewHost creates and initializes a new Host object using a
+// ManagedObjectReference and the VCenterDriver instance.
 func (d *VCenterDriver) NewHost(ref *types.ManagedObjectReference) *Host {
 	return &Host{
 		host:   object.NewHostSystem(d.client.Client, *ref),
 		driver: d,
 	}
 }
 
+// FindHost locates a host within the vCenter environment by its name. Returns
+// a Host object or an error if not found or if the retrieval process fails.
 func (d *VCenterDriver) FindHost(name string) (*Host, error) {
 	h, err := d.finder.HostSystem(d.ctx, name)
 	if err != nil {
@@ -32,6 +36,8 @@ func (d *VCenterDriver) FindHost(name string) (*Host, error) {
 	}, nil
 }
 
+// Info retrieves properties of the host object with optional filters specified
+// as parameters. If no parameters are provided, all properties are returned.
 func (h *Host) Info(params ...string) (*mo.HostSystem, error) {
 	var p []string
 	if len(params) == 0 {

builder/vsphere/driver/library.go

@@ -17,6 +17,8 @@ type Library struct {
 	library *library.Library
 }
 
+// FindContentLibraryByName retrieves a content library by its name. Returns a
+// Library object or an error if the library is not found.
 func (d *VCenterDriver) FindContentLibraryByName(name string) (*Library, error) {
 	lm := library.NewManager(d.restClient.client)
 	l, err := lm.GetLibraryByName(d.ctx, name)
@@ -29,6 +31,9 @@ func (d *VCenterDriver) FindContentLibraryByName(name string) (*Library, error)
 	}, nil
 }
 
+// FindContentLibraryItem retrieves a content library item by its name within
+// the specified library ID.  Returns the library item if found or an error if
+// the item is not found or the retrieval process fails.
 func (d *VCenterDriver) FindContentLibraryItem(libraryId string, name string) (*library.Item, error) {
 	lm := library.NewManager(d.restClient.client)
 	items, err := lm.GetLibraryItems(d.ctx, libraryId)
@@ -43,6 +48,10 @@ func (d *VCenterDriver) FindContentLibraryItem(libraryId string, name string) (*
 	return nil, fmt.Errorf("content library item %s not found", name)
 }
 
+// FindContentLibraryItemUUID retrieves the UUID of a content library item
+//
+//	based on the given library ID and item name. Returns the UUID if found or
+//	an error if the item is not found or the retrieval process fails.
 func (d *VCenterDriver) FindContentLibraryItemUUID(libraryId string, name string) (string, error) {
 	item, err := d.FindContentLibraryItem(libraryId, name)
 	if err != nil {
@@ -51,6 +60,10 @@ func (d *VCenterDriver) FindContentLibraryItemUUID(libraryId string, name string
 	return item.ID, nil
 }
 
+// FindContentLibraryFileDatastorePath checks if the provided ISO path belongs
+// to a content library and retrieves its datastore path. Returns the datastore
+// path if the ISO path is a content library path or an error if the path is
+// not identified as a content library path or if the retrieval process fails.
 func (d *VCenterDriver) FindContentLibraryFileDatastorePath(isoPath string) (string, error) {
 	log.Printf("Check if ISO path is a Content Library path")
 	err := d.restClient.Login(d.ctx)
@@ -98,6 +111,8 @@ func (d *VCenterDriver) FindContentLibraryFileDatastorePath(isoPath string) (str
 	return path.Join(libItemDir, isoFilePath), nil
 }
 
+// UpdateContentLibraryItem updates the metadata of a content library item,
+// such as its name and description. Returns an error if the update fails.
 func (d *VCenterDriver) UpdateContentLibraryItem(item *library.Item, name string, description string) error {
 	lm := library.NewManager(d.restClient.client)
 	item.Patch(&library.Item{
@@ -112,6 +127,8 @@ type LibraryFilePath struct {
 	path string
 }
 
+// Validate checks the format of the LibraryFilePath and returns an error if
+// the path is not in the expected format.
 func (l *LibraryFilePath) Validate() error {
 	l.path = strings.TrimLeft(l.path, "/")
 	parts := strings.Split(l.path, "/")
@@ -121,14 +138,17 @@ func (l *LibraryFilePath) Validate() error {
 	return nil
 }
 
+// GetLibraryName retrieves the library name from the content library file path.
 func (l *LibraryFilePath) GetLibraryName() string {
 	return strings.Split(l.path, "/")[0]
 }
 
+// GetLibraryItemName retrieves the library item name from the content library file path.
 func (l *LibraryFilePath) GetLibraryItemName() string {
 	return strings.Split(l.path, "/")[1]
 }
 
+// GetFileName retrieves the file name from the content library file path.
 func (l *LibraryFilePath) GetFileName() string {
 	return strings.Split(l.path, "/")[2]
 }

builder/vsphere/driver/network.go

@@ -16,13 +16,17 @@ type Network struct {
 	network object.NetworkReference
 }
 
+// NewNetwork creates and initializes a new Network object using the provided
+// ManagedObjectReference.
 func (d *VCenterDriver) NewNetwork(ref *types.ManagedObjectReference) *Network {
 	return &Network{
 		network: object.NewNetwork(d.client.Client, *ref),
 		driver:  d,
 	}
 }
 
+// FindNetwork locates a network by its name within the vCenter context.
+// Returns a Network object or an error if the network is not found.
 func (d *VCenterDriver) FindNetwork(name string) (*Network, error) {
 	n, err := d.finder.Network(d.ctx, name)
 	if err != nil {
@@ -34,6 +38,8 @@ func (d *VCenterDriver) FindNetwork(name string) (*Network, error) {
 	}, nil
 }
 
+// FindNetworks retrieves a list of networks in the vCenter matching the
+// provided name and returns them as Network objects.
 func (d *VCenterDriver) FindNetworks(name string) ([]*Network, error) {
 	ns, err := d.finder.NetworkList(d.ctx, name)
 	if err != nil {
@@ -49,6 +55,9 @@ func (d *VCenterDriver) FindNetworks(name string) ([]*Network, error) {
 	return networks, nil
 }
 
+// Info retrieves the properties of the network object with optional filters
+// specified as parameters. If no parameters are provided, all properties are
+// returned.
 func (n *Network) Info(params ...string) (*mo.Network, error) {
 	var p []string
 	if len(params) == 0 {
@@ -75,6 +84,7 @@ type MultipleNetworkFoundError struct {
 	append string
 }
 
+// Error returns a formatted error message for the MultipleNetworkFoundError.
 func (e *MultipleNetworkFoundError) Error() string {
 	return fmt.Sprintf("'%s' resolves to more than one network name; %s", e.path, e.append)
 }