doc: document structs used in API group interfaces

Author: alexander-ding

pkg/disk/types.go

@@ -8,6 +8,7 @@ type DiskLocation struct {
 }
 
 type ListDiskLocationsRequest struct {
+	// Intentionally empty
 }
 
 type ListDiskLocationsResponse struct {
@@ -21,20 +22,26 @@ type PartitionDiskRequest struct {
 }
 
 type PartitionDiskResponse struct {
+	// Intentionally empty
 }
 
 type RescanRequest struct {
+	// Intentionally empty
 }
 
 type RescanResponse struct {
+	// Intentionally empty
 }
 
 type ListDiskIDsRequest struct {
+	// Intentionally empty
 }
 
 type DiskIDs struct {
 	// Map of Disk ID types and Disk ID values
-	Page83       string
+	Page83 string
+
+	// The disk serial number
 	SerialNumber string
 }
 
@@ -44,6 +51,7 @@ type ListDiskIDsResponse struct {
 }
 
 type GetDiskStatsRequest struct {
+	// Disk device number of the disk to get the stats from
 	DiskNumber uint32
 }
 

pkg/filesystem/types.go

@@ -1,24 +1,20 @@
 package filesystem
 
-// PathExistsRequest is the internal representation of requests to the PathExists endpoint.
 type PathExistsRequest struct {
 	// The path whose existence we want to check in the host's filesystem
 	Path string
 }
 
-// PathExistsResponse is the internal representation of responses from the PathExists endpoint.
 type PathExistsResponse struct {
 	// Indicates whether the path in PathExistsRequest exists in the host's filesystem
 	Exists bool
 }
 
-// PathValidRequest is the internal representation of requests to the PathValid endpoint.
 type PathValidRequest struct {
 	// The path whose validity we want to check in the host's filesystem
 	Path string
 }
 
-// PathValidResponse is the internal representation of responses from the PathValid endpoint.
 type PathValidResponse struct {
 	// Indicates whether the path in PathValidRequest is a valid path
 	Valid bool
@@ -47,6 +43,7 @@ type MkdirRequest struct {
 }
 
 type MkdirResponse struct {
+	// Intentionally empty
 }
 
 type RmdirRequest struct {
@@ -66,11 +63,13 @@ type RmdirRequest struct {
 	// Path cannot be a file of type symlink.
 	// Maximum path length will be capped to 260 characters.
 	Path string
+
 	// Force remove all contents under path (if any).
 	Force bool
 }
 
 type RmdirResponse struct {
+	// Intentionally empty
 }
 
 type RmdirContentsRequest struct {
@@ -93,6 +92,7 @@ type RmdirContentsRequest struct {
 }
 
 type RmdirContentsResponse struct {
+	// Intentionally empty
 }
 
 type CreateSymlinkRequest struct {
@@ -111,6 +111,7 @@ type CreateSymlinkRequest struct {
 	// source_path cannot already exist in the host filesystem.
 	// Maximum path length will be capped to 260 characters.
 	SourcePath string
+
 	// Target path is the location of the new directory entry to be created in the host's filesystem.
 	// All special characters allowed by Windows in path names will be allowed
 	// except for restrictions noted below. For details, please check:
@@ -130,12 +131,15 @@ type CreateSymlinkRequest struct {
 }
 
 type CreateSymlinkResponse struct {
+	// Intentionally empty
 }
 
 type IsSymlinkRequest struct {
+	// The path whose existence as a symlink we want to check in the host's filesystem
 	Path string
 }
 
 type IsSymlinkResponse struct {
+	// Indicates whether the path in IsSymlinkRequest is a symlink
 	IsSymlink bool
 }

pkg/iscsi/types.go

@@ -75,6 +75,7 @@ type DiscoverTargetPortalResponse struct {
 type GetTargetDisksRequest struct {
 	// Target portal whose disks will be queried
 	TargetPortal *TargetPortal
+
 	// IQN of the iSCSI Target
 	Iqn string
 }
@@ -86,6 +87,7 @@ type GetTargetDisksResponse struct {
 }
 
 type ListTargetPortalsRequest struct {
+	// Intentionally empty
 }
 
 type ListTargetPortalsResponse struct {
@@ -105,6 +107,7 @@ type RemoveTargetPortalResponse struct {
 type TargetPortal struct {
 	// iSCSI Target (server) address
 	TargetAddress string
+
 	// iSCSI Target port (default iSCSI port is 3260)
 	TargetPort uint32
 }

pkg/smb/types.go

@@ -1,20 +1,44 @@
 package smb
 
 type NewSMBGlobalMappingRequest struct {
+	// A remote SMB share to mount
+	// All unicode characters allowed in SMB server name specifications are
+	// permitted except for restrictions below
+	//
+	// Restrictions:
+	// SMB remote path specified in the format: \\server-name\sharename, \\server.fqdn\sharename or \\a.b.c.d\sharename
+	// If not an IP address, share name has to be a valid DNS name.
+	// UNC specifications to local paths or prefix: \\?\ is not allowed.
+	// Characters: + [ ] " / : ; | < > , ? * = $ are not allowed
 	RemotePath string
-	LocalPath  string
-	Username   string
-	Password   string
+
+	// Optional local path to mount the SMB on
+	LocalPath string
+
+	// Username credential associated with the share
+	Username string
+
+	// Password credential associated with the share
+	Password string
 }
 
 type NewSMBGlobalMappingResponse struct {
-	// Intentionally empty.
+	// Intentionally empty
 }
 
 type RemoveSMBGlobalMappingRequest struct {
+	// A remote SMB share mapping to remove
+	// All unicode characters allowed in SMB server name specifications are
+	// permitted except for restrictions below
+	//
+	// Restrictions:
+	// SMB share specified in the format: \\server-name\sharename, \\server.fqdn\sharename or \\a.b.c.d\sharename
+	// If not an IP address, share name has to be a valid DNS name.
+	// UNC specifications to local paths or prefix: \\?\ is not allowed.
+	// Characters: + [ ] " / : ; | < > , ? * = $ are not allowed
 	RemotePath string
 }
 
 type RemoveSMBGlobalMappingResponse struct {
-	// Intentionally empty.
+	// Intentionally empty
 }

pkg/system/types.go

@@ -1,9 +1,11 @@
 package system
 
 type GetBIOSSerialNumberRequest struct {
+	// Intentionally empty
 }
 
 type GetBIOSSerialNumberResponse struct {
+	// Serial number
 	SerialNumber string
 }
 
@@ -30,6 +32,7 @@ type StopServiceResponse struct {
 
 type ServiceStatus uint32
 
+// https://docs.microsoft.com/en-us/windows/win32/api/winsvc/ns-winsvc-service_status#members
 const (
 	SERVICE_STATUS_UNKNOWN ServiceStatus = iota
 	SERVICE_STATUS_STOPPED
@@ -43,6 +46,7 @@ const (
 
 type Startype uint32
 
+// https://docs.microsoft.com/en-us/windows/win32/api/winsvc/nf-winsvc-changeserviceconfiga
 const (
 	START_TYPE_BOOT Startype = iota
 	START_TYPE_SYSTEM
@@ -60,9 +64,9 @@ type GetServiceResponse struct {
 	// Service display name
 	DisplayName string
 
-	// Service start type.
+	// Service start type
 	// Used to control whether a service will start on boot, and if so on which
-	// boot phase.
+	// boot phase
 	StartType Startype
 
 	// Service status, e.g. stopped, running, paused

pkg/volume/types.go

@@ -1,89 +1,121 @@
 package volume
 
 type ListVolumesOnDiskRequest struct {
-	DiskNumber      uint32
+	// Disk device number of the disk to query for volumes
+	DiskNumber uint32
+
+	// The partition number (optional), by default it uses the first partition of the disk
 	PartitionNumber uint32
 }
 
 type ListVolumesOnDiskResponse struct {
+	// Volume device IDs of volumes on the specified disk
 	VolumeIds []string
 }
 
 type MountVolumeRequest struct {
-	VolumeId   string
+	// Volume device ID of the volume to mount
+	VolumeId string
+
+	// Path in the host's file system where the volume needs to be mounted
 	TargetPath string
 }
 
 type MountVolumeResponse struct {
+	// Intentionally empty
 }
 
 type IsVolumeFormattedRequest struct {
+	// Volume device ID of the volume to check
 	VolumeId string
 }
 
 type IsVolumeFormattedResponse struct {
+	// Whether the volume is formatted with NTFS
 	Formatted bool
 }
 
 type FormatVolumeRequest struct {
+	// Volume device ID of the volume to format
 	VolumeId string
 }
 
 type FormatVolumeResponse struct {
+	// Intentionally empty
 }
 
 type WriteVolumeCacheRequest struct {
+	// Volume device ID of the volume to flush the cache
 	VolumeId string
 }
 
 type WriteVolumeCacheResponse struct {
+	// Intentionally empty
 }
 
 type UnmountVolumeRequest struct {
-	VolumeId   string
+	// Volume device ID of the volume to dismount
+	VolumeId string
+
+	// Path where the volume has been mounted
 	TargetPath string
 }
 
 type UnmountVolumeResponse struct {
+	// Intentionally empty
 }
 
 type ResizeVolumeRequest struct {
-	VolumeId  string
+	// Volume device ID of the volume to resize
+	VolumeId string
+
+	// New size in bytes of the volume
 	SizeBytes int64
 }
 
 type ResizeVolumeResponse struct {
+	// Intentionally empty
 }
 
 type GetVolumeStatsRequest struct {
+	// Volume device Id of the volume to get the stats for
 	VolumeId string
 }
 
 type GetVolumeStatsResponse struct {
+	// Total bytes
 	TotalBytes int64
-	UsedBytes  int64
+
+	// Used bytes
+	UsedBytes int64
 }
 
 type GetDiskNumberFromVolumeIDRequest struct {
+	// Volume device ID of the volume to get the disk number for
 	VolumeId string
 }
 
 type GetDiskNumberFromVolumeIDResponse struct {
+	// Corresponding disk number
 	DiskNumber uint32
 }
 
 type GetVolumeIDFromTargetPathRequest struct {
+	// The target path
 	TargetPath string
 }
 
 type GetVolumeIDFromTargetPathResponse struct {
+	// The volume device ID
 	VolumeId string
 }
 
 type GetClosestVolumeIDFromTargetPathRequest struct {
+	// The target path
 	TargetPath string
 }
 
 type GetClosestVolumeIDFromTargetPathResponse struct {
+	// The volume device ID
 	VolumeId string
 }