doc: document API group interface methods

Author: alexander-ding

pkg/disk/disk.go

@@ -17,13 +17,28 @@ type Interface interface {
 	DiskStats(context.Context, *DiskStatsRequest) (*DiskStatsResponse, error)
 	GetAttachState(context.Context, *GetAttachStateRequest) (*GetAttachStateResponse, error)
 	GetDiskNumberByName(context.Context, *GetDiskNumberByNameRequest) (*GetDiskNumberByNameResponse, error)
+	// GetDiskState gets the offline/online state of a disk.
 	GetDiskState(context.Context, *GetDiskStateRequest) (*GetDiskStateResponse, error)
+
+	// GetDiskStats returns the stats of a disk (currently it returns the disk size).
 	GetDiskStats(context.Context, *GetDiskStatsRequest) (*GetDiskStatsResponse, error)
+
+	// ListDiskIDs returns a map of DiskID objects where the key is the disk number.
 	ListDiskIDs(context.Context, *ListDiskIDsRequest) (*ListDiskIDsResponse, error)
+
+	// ListDiskLocations returns locations <Adapter, Bus, Target, LUN ID> of all
+	// disk devices enumerated by the host.
 	ListDiskLocations(context.Context, *ListDiskLocationsRequest) (*ListDiskLocationsResponse, error)
+
+	// PartitionDisk initializes and partitions a disk device with the GPT partition style
+	// (if the disk has not been partitioned already) and returns the resulting volume device ID.
 	PartitionDisk(context.Context, *PartitionDiskRequest) (*PartitionDiskResponse, error)
+
+	// Rescan refreshes the host's storage cache.
 	Rescan(context.Context, *RescanRequest) (*RescanResponse, error)
 	SetAttachState(context.Context, *SetAttachStateRequest) (*SetAttachStateResponse, error)
+
+	// SetDiskState sets the offline/online state of a disk.
 	SetDiskState(context.Context, *SetDiskStateRequest) (*SetDiskStateResponse, error)
 }
 

pkg/filesystem/filesystem.go

@@ -12,14 +12,31 @@ type Filesystem struct {
 }
 
 type Interface interface {
+	// CreateSymlink creates a symbolic link called target_path that points to source_path
+	// in the host filesystem (target_path is the name of the symbolic link created,
+	// source_path is the existing path).
 	CreateSymlink(context.Context, *CreateSymlinkRequest) (*CreateSymlinkResponse, error)
 	IsMountPoint(context.Context, *IsMountPointRequest) (*IsMountPointResponse, error)
+
+	// IsSymlink checks if a given path is a symlink.
 	IsSymlink(context.Context, *IsSymlinkRequest) (*IsSymlinkResponse, error)
 	LinkPath(context.Context, *LinkPathRequest) (*LinkPathResponse, error)
+
+	// Mkdir creates a directory at the requested path in the host filesystem.
 	Mkdir(context.Context, *MkdirRequest) (*MkdirResponse, error)
+
+	// PathExists checks if the requested path exists in the host filesystem.
 	PathExists(context.Context, *PathExistsRequest) (*PathExistsResponse, error)
+
+	// PathValid checks if the given path is accessible.
 	PathValid(context.Context, *PathValidRequest) (*PathValidResponse, error)
+
+	// Rmdir removes the directory at the requested path in the host filesystem.
+	// This may be used for unlinking a symlink created through CreateSymlink.
 	Rmdir(context.Context, *RmdirRequest) (*RmdirResponse, error)
+
+	// RmdirContents removes the contents of a directory in the host filesystem.
+	// Unlike Rmdir it won't delete the requested path, it'll only delete its contents.
 	RmdirContents(context.Context, *RmdirContentsRequest) (*RmdirContentsResponse, error)
 }
 
@@ -50,7 +67,6 @@ func (f *Filesystem) PathExists(ctx context.Context, request *PathExistsRequest)
 	}, err
 }
 
-// PathValid checks if the given path is accessible.
 func (f *Filesystem) PathValid(ctx context.Context, request *PathValidRequest) (*PathValidResponse, error) {
 	klog.V(2).Infof("Request: PathValid with path %q", request.Path)
 	valid, err := f.hostAPI.PathValid(request.Path)

pkg/iscsi/iscsi.go

@@ -15,13 +15,39 @@ type IsCSI struct {
 }
 
 type Interface interface {
+	// AddTargetPortal registers an iSCSI target network address for later
+	// discovery.
+	// AddTargetPortal currently does not support selecting different NICs or
+	// a different iSCSI initiator (e.g a hardware initiator). This means that
+	// Windows will select the initiator NIC and instance on its own.
 	AddTargetPortal(context.Context, *AddTargetPortalRequest) (*AddTargetPortalResponse, error)
+
+	// ConnectTarget connects to an iSCSI Target
 	ConnectTarget(context.Context, *ConnectTargetRequest) (*ConnectTargetResponse, error)
+
+	// DisconnectTarget disconnects from an iSCSI Target
 	DisconnectTarget(context.Context, *DisconnectTargetRequest) (*DisconnectTargetResponse, error)
+
+	// DiscoverTargetPortal initiates discovery on an iSCSI target network address
+	// and returns discovered IQNs.
 	DiscoverTargetPortal(context.Context, *DiscoverTargetPortalRequest) (*DiscoverTargetPortalResponse, error)
+
+	// GetTargetDisks returns the disk addresses that correspond to an iSCSI
+	// target
 	GetTargetDisks(context.Context, *GetTargetDisksRequest) (*GetTargetDisksResponse, error)
+
+	// ListTargetPortal lists all currently registered iSCSI target network
+	// addresses.
 	ListTargetPortals(context.Context, *ListTargetPortalsRequest) (*ListTargetPortalsResponse, error)
+
+	// RemoveTargetPortal removes an iSCSI target network address registration.
 	RemoveTargetPortal(context.Context, *RemoveTargetPortalRequest) (*RemoveTargetPortalResponse, error)
+
+	// SetMutualChapSecret sets the default CHAP secret that all initiators on
+	// this machine (node) use to authenticate the target on mutual CHAP
+	// authentication.
+	// NOTE: This method affects global node state and should only be used
+	//       with consideration to other CSI drivers that run concurrently.
 	SetMutualChapSecret(context.Context, *SetMutualChapSecretRequest) (*SetMutualChapSecretResponse, error)
 }
 

pkg/smb/smb.go

@@ -16,7 +16,10 @@ type Smb struct {
 }
 
 type Interface interface {
+	// NewSmbGlobalMapping creates an SMB mapping on the SMB client to an SMB share.
 	NewSmbGlobalMapping(context.Context, *NewSmbGlobalMappingRequest) (*NewSmbGlobalMappingResponse, error)
+
+	// RemoveSmbGlobalMapping removes the SMB mapping to an SMB share.
 	RemoveSmbGlobalMapping(context.Context, *RemoveSmbGlobalMappingRequest) (*RemoveSmbGlobalMappingResponse, error)
 }
 

pkg/system/system.go

@@ -12,9 +12,20 @@ type System struct {
 }
 
 type Interface interface {
+	// GetBIOSSerialNumber returns the device's serial number
 	GetBIOSSerialNumber(context.Context, *GetBIOSSerialNumberRequest) (*GetBIOSSerialNumberResponse, error)
+
+	// GetService queries a Windows service state
 	GetService(context.Context, *GetServiceRequest) (*GetServiceResponse, error)
+
+	// StartService starts a Windows service
+	// NOTE: This method affects global node state and should only be used
+	//       with consideration to other CSI drivers that run concurrently.
 	StartService(context.Context, *StartServiceRequest) (*StartServiceResponse, error)
+
+	// StopService stops a Windows service
+	// NOTE: This method affects global node state and should only be used
+	//       with consideration to other CSI drivers that run concurrently.
 	StopService(context.Context, *StopServiceRequest) (*StopServiceResponse, error)
 }
 

pkg/volume/volume.go

@@ -15,19 +15,43 @@ type Volume struct {
 
 type Interface interface {
 	DismountVolume(context.Context, *DismountVolumeRequest) (*DismountVolumeResponse, error)
+	// FormatVolume formats a volume with NTFS.
 	FormatVolume(context.Context, *FormatVolumeRequest) (*FormatVolumeResponse, error)
+
+	// GetClosestVolumeIDFromTargetPath gets the closest volume id for a given target path
+	// by following symlinks and moving up in the filesystem, if after moving up in the filesystem
+	// we get to a DriveLetter then the volume corresponding to this drive letter is returned instead.
 	GetClosestVolumeIDFromTargetPath(context.Context, *GetClosestVolumeIDFromTargetPathRequest) (*GetClosestVolumeIDFromTargetPathResponse, error)
+
+	// GetDiskNumberFromVolumeID gets the disk number of the disk where the volume is located.
 	GetDiskNumberFromVolumeID(context.Context, *GetDiskNumberFromVolumeIDRequest) (*GetDiskNumberFromVolumeIDResponse, error)
 	GetVolumeDiskNumber(context.Context, *VolumeDiskNumberRequest) (*VolumeDiskNumberResponse, error)
 	GetVolumeIDFromMount(context.Context, *VolumeIDFromMountRequest) (*VolumeIDFromMountResponse, error)
+
+	// GetVolumeIDFromTargetPath gets the volume id for a given target path.
 	GetVolumeIDFromTargetPath(context.Context, *GetVolumeIDFromTargetPathRequest) (*GetVolumeIDFromTargetPathResponse, error)
+
+	// GetVolumeStats gathers total bytes and used bytes for a volume.
 	GetVolumeStats(context.Context, *GetVolumeStatsRequest) (*GetVolumeStatsResponse, error)
+
+	// IsVolumeFormatted checks if a volume is formatted.
 	IsVolumeFormatted(context.Context, *IsVolumeFormattedRequest) (*IsVolumeFormattedResponse, error)
+
+	// ListVolumesOnDisk returns the volume IDs (in \\.\Volume{GUID} format) for all volumes from a
+	// given disk number and partition number (optional)
 	ListVolumesOnDisk(context.Context, *ListVolumesOnDiskRequest) (*ListVolumesOnDiskResponse, error)
+
+	// MountVolume mounts the volume at the requested global staging path.
 	MountVolume(context.Context, *MountVolumeRequest) (*MountVolumeResponse, error)
+
+	// ResizeVolume performs resizing of the partition and file system for a block based volume.
 	ResizeVolume(context.Context, *ResizeVolumeRequest) (*ResizeVolumeResponse, error)
+
+	// UnmountVolume flushes data cache to disk and removes the global staging path.
 	UnmountVolume(context.Context, *UnmountVolumeRequest) (*UnmountVolumeResponse, error)
 	VolumeStats(context.Context, *VolumeStatsRequest) (*VolumeStatsResponse, error)
+
+	// WriteVolumeCache write volume cache to disk.
 	WriteVolumeCache(context.Context, *WriteVolumeCacheRequest) (*WriteVolumeCacheResponse, error)
 }