From 2b5ec9f76d2ed1f7e6c4e643f8f91db2ae12acf8 Mon Sep 17 00:00:00 2001 From: Leoswaldo Macias Date: Tue, 2 Aug 2016 16:58:13 -0500 Subject: [PATCH] payloads: document all variables with missing proper description In the past, some variables where added with a generic description as " 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 --- payloads/assignpublicIP.go | 29 +++++++++++++------- payloads/compute.go | 7 ++--- payloads/configure.go | 32 +++++++++++++--------- payloads/evacuate.go | 4 +-- payloads/publicIPassigned.go | 4 +-- payloads/start.go | 52 +++++++++++++++++++++--------------- 6 files changed, 77 insertions(+), 51 deletions(-) diff --git a/payloads/assignpublicIP.go b/payloads/assignpublicIP.go index 39c33a80b..5465ad169 100644 --- 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 index 6c0b4ba92..b7b5192a6 100644 --- 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 index 6f77f0fd3..4b2b5bf22 100644 --- 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,7 +79,8 @@ 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"` @@ -83,13 +88,16 @@ type ConfigureLauncher struct { 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 index 44845f8ab..1ccc174a7 100644 --- 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 index f619d77a5..3f99941ae 100644 --- a/payloads/publicIPassigned.go +++ b/payloads/publicIPassigned.go @@ -16,7 +16,7 @@ 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"` @@ -24,7 +24,7 @@ type PublicIPEvent struct { 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 index 23cbd27b1..041d2b5bd 100644 --- 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,13 +198,13 @@ 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 @@ -206,19 +212,21 @@ type RestartCmd struct { // 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"` }