Merge pull request #427 from leoswaldo/leoswaldo/topic/payloads-docs

payloads: document all variables with missing proper description

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"`

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"`

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"`
 }

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"`
 }

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"`
 }

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"`
 }