payloads: document all variables with missing proper description

In the past, some variables where added with a generic description as "<variable> is reserved for future use". This commit contains all new proper descriptions for the variables. With this change we ensure our documentation is aligned to the development standard guideline ciao is following. Fixes #397 Signed-off-by: Leoswaldo Macias <[email protected]>
ciao-project · Aug 4, 2016 · 2b5ec9f · 2b5ec9f
1 parent 320fc8a
commit 2b5ec9f
Show file tree

Hide file tree

Showing 6 changed files with 77 additions and 51 deletions.
diff --git a/payloads/assignpublicIP.go b/payloads/assignpublicIP.go
@@ -16,7 +16,7 @@
 
 package payloads
 
-// PublicIPCommand is reserved for future use.
+// PublicIPCommand contains information about a IP and its associated data.
 type PublicIPCommand struct {
 	ConcentratorUUID string `yaml:"concentrator_uuid"`
 	TenantUUID       string `yaml:"tenant_uuid"`
@@ -26,37 +26,46 @@ type PublicIPCommand struct {
 	VnicMAC          string `yaml:"vnic_mac"`
 }
 
-// CommandAssignPublicIP is reserved for future use.
+// CommandAssignPublicIP is a wrapper around PublicIPCommand. It is the
+// AssignPublicIP command payload.
 type CommandAssignPublicIP struct {
 	AssignIP PublicIPCommand `yaml:"assign_public_ip"`
 }
 
-// CommandReleasePublicIP is reserved for future use.
+// CommandReleasePublicIP is a wrapper around PublicIPCommand. It is the
+// ReleasePublicIP command payload.
 type CommandReleasePublicIP struct {
 	ReleaseIP PublicIPCommand `yaml:"release_public_ip"`
 }
 
-// PublicIPFailureReason is reserved for future use.
+// PublicIPFailureReason represents the potential
+// AssignPublicIP/ReleasePublicIP commands failure reasons.
 type PublicIPFailureReason string
 
 const (
-	// PublicIPNoInstance is reserved for future use.
+	// PublicIPNoInstance indicates that a public IP assignment/release failed
+	// because the corresponding instance does not exist
 	PublicIPNoInstance PublicIPFailureReason = "no_instance"
 
-	// PublicIPInvalidPayload is reserved for future use.
+	// PublicIPInvalidPayload constant is used to denote when YAML payload
+	//  is corrupt.
 	PublicIPInvalidPayload = "invalid_payload"
 
-	// PublicIPInvalidData is reserved for future use.
+	// PublicIPInvalidData constant is used to denote when command section
+	// of YAML payload is corrupt or missing required information.
 	PublicIPInvalidData = "invalid_data"
 
-	// PublicIPAssignFailure is reserved for future use.
+	// PublicIPAssignFailure constant is used to denote when Public IP assignment
+	// operation failed.
 	PublicIPAssignFailure = "assign_failure"
 
-	// PublicIPReleaseFailure is reserved for future use.
+	// PublicIPReleaseFailure constant is used to denote when Public IP release
+	// operation failed.
 	PublicIPReleaseFailure = "release_failure"
 )
 
-// ErrorPublicIPFailure is reserved for future use.
+// ErrorPublicIPFailure represents the PublicIPFailure SSNTP error payload.
+// It includes information about the IP itself and the actual reason for failure.
 type ErrorPublicIPFailure struct {
 	ConcentratorUUID string                `yaml:"concentrator_uuid"`
 	TenantUUID       string                `yaml:"tenant_uuid"`

diff --git a/payloads/compute.go b/payloads/compute.go
@@ -34,7 +34,8 @@ type Addresses struct {
 	Private []PrivateAddresses `json:"private"`
 }
 
-// Link is reserved for future use.
+// Link contains the address to a compute resource, like e.g. a Flavor or an
+// Image.
 type Link struct {
 	Href string `json:"href"`
 	Rel  string `json:"rel"`
@@ -372,7 +373,7 @@ type CiaoClusterStatus struct {
 	} `json:"cluster"`
 }
 
-// CNCIDetail is reserved for future use.
+// CNCIDetail stores the IPv4 for a CNCI Agent.
 type CNCIDetail struct {
 	IPv4 string `json:"IPv4"`
 }
@@ -398,7 +399,7 @@ type CiaoTracesSummary struct {
 	Summaries []CiaoTraceSummary `json:"summaries"`
 }
 
-// CiaoFrameStat is reserved for future use
+// CiaoFrameStat contains the elapsed time statistics for a frame.
 type CiaoFrameStat struct {
 	ID               string  `json:"node_id"`
 	TotalElapsedTime float64 `json:"total_elapsed_time"`

diff --git a/payloads/configure.go b/payloads/configure.go
@@ -16,25 +16,27 @@
 
 package payloads
 
-// ServiceType is reserved for future use.
+// ServiceType is used to define OpenStack service types, like e.g. the image
+// or identity ones.
 type ServiceType string
 
-// StorageType is reserved for future use.
+// StorageType is used to define the configuration backend storage type.
 type StorageType string
 
 const (
-	// Glance is reserved for future use.
+	// Glance is used to define the imaging service.
 	Glance ServiceType = "glance"
 
-	// Keystone is reserved for future use.
+	// Keystone is used to define the identity service.
 	Keystone ServiceType = "keystone"
 )
 
 const (
-	// Filesystem is reserved for future use.
+	// Filesystem defines the local filesystem backend storage type for the
+	// configuration data.
 	Filesystem StorageType = "file"
 
-	// Etcd is reserved for future use.
+	// Etcd defines the etcd backend storage type for the configuration data.
 	Etcd StorageType = "etcd"
 )
 
@@ -60,13 +62,15 @@ func (s StorageType) String() string {
 	return ""
 }
 
-// ConfigureScheduler is reserved for future use.
+// ConfigureScheduler contains the unmarshalled configurations for the
+// scheduler service.
 type ConfigureScheduler struct {
 	ConfigStorageType StorageType `yaml:"storage_type"`
 	ConfigStorageURI  string      `yaml:"storage_uri"`
 }
 
-// ConfigureController is reserved for future use.
+// ConfigureController contains the unmarshalled configurations for the
+// controller service.
 type ConfigureController struct {
 	ComputePort      int    `yaml:"compute_port"`
 	HTTPSCACert      string `yaml:"compute_ca"`
@@ -75,21 +79,25 @@ type ConfigureController struct {
 	IdentityPassword string `yaml:"identity_password"`
 }
 
-// ConfigureLauncher is reserved for future use.
+// ConfigureLauncher contains the unmarshalled configurations for the
+// launcher service.
 type ConfigureLauncher struct {
 	ComputeNetwork    string `yaml:"compute_net"`
 	ManagementNetwork string `yaml:"mgmt_net"`
 	DiskLimit         bool   `yaml:"disk_limit"`
 	MemoryLimit       bool   `yaml:"mem_limit"`
 }
 
-// ConfigureService is reserved for future use.
+// ConfigureService contains the unmarshalled configurations for the resources
+// of the configurations.
 type ConfigureService struct {
 	Type ServiceType `yaml:"type"`
 	URL  string      `yaml:"url"`
 }
 
-// ConfigurePayload is reserved for future use.
+// ConfigurePayload is a wrapper to read and unmarshall all posible
+// configurations for the following services: scheduler, controller, launcher,
+//  imaging and identity.
 type ConfigurePayload struct {
 	Scheduler       ConfigureScheduler  `yaml:"scheduler"`
 	Controller      ConfigureController `yaml:"controller"`
@@ -98,7 +106,7 @@ type ConfigurePayload struct {
 	IdentityService ConfigureService    `yaml:"identity_service"`
 }
 
-// Configure is reserved for future use.
+// Configure represents the SSNTP CONFIGURE command payload.
 type Configure struct {
 	Configure ConfigurePayload `yaml:"configure"`
 }

diff --git a/payloads/evacuate.go b/payloads/evacuate.go
@@ -16,12 +16,12 @@
 
 package payloads
 
-// EvacuateCmd is reserved for future use.
+// EvacuateCmd contains the nodeID of a SSNTP Agent.
 type EvacuateCmd struct {
 	WorkloadAgentUUID string `yaml:"workload_agent_uuid"`
 }
 
-// Evacuate is reserved for future use.
+// Evacuate represents the SSNTP EVACUATE command payload.
 type Evacuate struct {
 	Evacuate EvacuateCmd `yaml:"evacuate"`
 }
diff --git a/payloads/publicIPassigned.go b/payloads/publicIPassigned.go
@@ -16,15 +16,15 @@
 
 package payloads
 
-// PublicIPEvent is reserved for future use.
+// PublicIPEvent contains the basic information of Public IP event.
 type PublicIPEvent struct {
 	ConcentratorUUID string `yaml:"concentrator_uuid"`
 	InstanceUUID     string `yaml:"instance_uuid"`
 	PublicIP         string `yaml:"public_ip"`
 	PrivateIP        string `yaml:"private_ip"`
 }
 
-// EventPublicIPAssigned is reserved for future use.
+// EventPublicIPAssigned represents the SSNTP PublicIPAssigned event payload.
 type EventPublicIPAssigned struct {
 	AssignedIP PublicIPEvent `yaml:"public_ip_assigned"`
 }
diff --git a/payloads/start.go b/payloads/start.go
@@ -32,13 +32,16 @@ type Resource string
 type Hypervisor string
 
 const (
-	// All is reserved for future usage.
+	// All used to indicate all persistent scenario, in this case it
+	// indicates to act in all instances.
 	All Persistence = "all"
 
-	// VM is reserved for future usage.
+	// VM used to indicate in a instance persistent scenario, in this case it
+	// indicates to act in only one instance.
 	VM = "vm"
 
-	// Host is reserved for future usage.
+	// Host used to indicate in a Host persistent scenario, in this case it
+	// indicates to act in only in the instances of a host.
 	Host = "host"
 )
 
@@ -97,22 +100,22 @@ type RequestedResource struct {
 	Mandatory bool `yaml:"mandatory"`
 }
 
-// EstimatedResource is reserved for future usage.
+// EstimatedResource contains the definition of estimated value of a resource.
 type EstimatedResource struct {
-	// Type is reserved for future usage.
+	// Type is the resource type.
 	Type Resource `yaml:"type"`
 
-	// Value is reserved for future usage.
+	// value is the value of the resource.
 	Value int `yaml:"value"`
 }
 
-// NetworkResources contains all the networking information for an instance
+// NetworkResources contains all the networking information for an instance.
 type NetworkResources struct {
 
-	// VnicMAC contains the MAC address of an instance's VNIC
+	// VnicMAC contains the MAC address of an instance's VNIC.
 	VnicMAC string `yaml:"vnic_mac"`
 
-	// VnicUUID is a cluster unique UUID assigned to an instance's VNIC
+	// VnicUUID is a cluster unique UUID assigned to an instance's VNIC.
 	VnicUUID string `yaml:"vnic_uuid"`
 
 	// ConcentratorUUID is the UUID of the CNCI instance.  Only specified
@@ -127,17 +130,20 @@ type NetworkResources struct {
 	// specified when creating CN instances.
 	Subnet string `yaml:"subnet"`
 
-	// SubnetKey is reserved for future usage.
+	// SubnetKey is the subnet identifier to which the instance
+	// is assigned.
 	SubnetKey string `yaml:"subnet_key"`
 
-	// SubnetUUID is reserved for future usage.
+	// SubnetUUID is the subnet ID of the subnet to which the instance is
+	//  assinged.
 	SubnetUUID string `yaml:"subnet_uuid"`
 
 	// PrivateIP represents the private IP address of an instance.  Only
 	// specified when creating CN instances.
 	PrivateIP string `yaml:"private_ip"`
 
-	// PublicIP is  reserved for future usage.
+	// PublicIP represents the current statu of the assignation of a Public
+	// IP.
 	PublicIP bool `yaml:"public_ip"`
 }
 
@@ -164,7 +170,7 @@ type StartCmd struct {
 	// Only used for qemu instances.
 	FWType Firmware `yaml:"fw_type"`
 
-	// InstancePersistence is reserved for future use.
+	// InstancePersistence is the persistence type for the instance.
 	InstancePersistence Persistence `yaml:"persistence"`
 
 	// VMType indicates whether we are creating a qemu or docker instance.
@@ -174,7 +180,7 @@ type StartCmd struct {
 	// assigned to the new instance.
 	RequestedResources []RequestedResource `yaml:"requested_resources"`
 
-	// EstimatedResources is reserved for future usage.
+	// EstimatedResources represents the estimated value of the instance resource.
 	EstimatedResources []EstimatedResource `yaml:"estimated_resources"`
 
 	// Networking contains all the information required to set up networking
@@ -192,33 +198,35 @@ type Start struct {
 
 // RestartCmd contains information needed to restart an instance.
 type RestartCmd struct {
-	// TenantUUID is reserved for future usage.
+	// TenantUUID is the tenant ID of the instance to restart.
 	TenantUUID string `yaml:"tenant_uuid"`
 
-	// InstanceUUID is the UUID of the instance to restart
+	// InstanceUUID is the UUID of the instance to restart.
 	InstanceUUID string `yaml:"instance_uuid"`
 
-	// ImageUUID  is reserved for future usage.
+	// ImageUUID  is the image ID fo the instance to restart.
 	ImageUUID string `yaml:"image_uuid"`
 
 	// WorkloadAgentUUID identifies the node on which the instance is
 	// running.  This information is needed by the scheduler to route
 	// the command to the correct CN/NN.
 	WorkloadAgentUUID string `yaml:"workload_agent_uuid"`
 
-	// FWType is reserved for future usage.
+	// FWType indicates the type of firmware needed to boot the instance.
 	FWType Firmware `yaml:"fw_type"`
 
-	// InstancePersistence is reserved for future usage.
+	// InstancePersistence is the persistence type for the instance.
 	InstancePersistence Persistence `yaml:"persistence"`
 
-	// RequestedResources is reserved for future usage.
+	// RequestedResources contains a list of the resources that are to be
+	// assigned to the new instance.
 	RequestedResources []RequestedResource `yaml:"requested_resources"`
 
-	// EstimatedResourcse is reserved for future usage.
+	// EstimatedResources represents the estimated value of the instance resource.
 	EstimatedResources []EstimatedResource `yaml:"estimated_resources"`
 
-	// Networking is reserved for future usage.
+	// Networking contains all the information required to set up networking
+	// for the new instance.
 	Networking NetworkResources `yaml:"networking"`
 }