Finishing documentation
diff --git a/openstack/networking/v2/ports/doc.go b/openstack/networking/v2/ports/doc.go
index 808de88..f16a4bb 100644
--- a/openstack/networking/v2/ports/doc.go
+++ b/openstack/networking/v2/ports/doc.go
@@ -1 +1,8 @@
+// Package ports contains functionality for working with Neutron port resources.
+// A port represents a virtual switch port on a logical network switch. Virtual
+// instances attach their interfaces into ports. The logical port also defines
+// the MAC address and the IP address(es) to be assigned to the interfaces
+// plugged into them. When IP addresses are associated to a port, this also
+// implies the port is associated with a subnet, as the IP address was taken
+// from the allocation pool for a specific subnet.
package ports
diff --git a/openstack/networking/v2/ports/errors.go b/openstack/networking/v2/ports/errors.go
index 55c01e9..111d977 100644
--- a/openstack/networking/v2/ports/errors.go
+++ b/openstack/networking/v2/ports/errors.go
@@ -7,5 +7,5 @@
}
var (
- ErrNetworkIDRequired = err("A Network ID is required")
+ errNetworkIDRequired = err("A Network ID is required")
)
diff --git a/openstack/networking/v2/ports/requests.go b/openstack/networking/v2/ports/requests.go
index cc0949f..78c96ab 100644
--- a/openstack/networking/v2/ports/requests.go
+++ b/openstack/networking/v2/ports/requests.go
@@ -9,6 +9,18 @@
"github.com/rackspace/gophercloud/pagination"
)
+func maybeString(original string) *string {
+ if original != "" {
+ return &original
+ }
+ return nil
+}
+
+// ListOpts allows the filtering and sorting of paginated collections through
+// the API. Filtering is achieved by passing in struct field values that map to
+// the port attributes you want to see returned. SortKey allows you to sort
+// by a particular port attribute. SortDir sets the direction, and is either
+// `asc' or `desc'. Marker and Limit are used for pagination.
type ListOpts struct {
Status string
Name string
@@ -18,18 +30,23 @@
DeviceOwner string
MACAddress string
ID string
- SecurityGroups string
DeviceID string
BindingHostID string
BindingVIFType string
BindingVNICType string
Limit int
- Page string
- PerPage string
+ Marker string
SortKey string
SortDir string
}
+// List returns a Pager which allows you to iterate over a collection of
+// ports. It accepts a ListOpts struct, which allows you to filter and sort
+// the returned collection for greater efficiency.
+//
+// Default policy settings return only those ports that are owned by the tenant
+// who submits the request, unless the request is submitted by an user with
+// administrative rights.
func List(c *gophercloud.ServiceClient, opts ListOpts) pagination.Pager {
// Build query parameters
q := make(map[string]string)
@@ -57,9 +74,6 @@
if opts.ID != "" {
q["id"] = opts.ID
}
- if opts.SecurityGroups != "" {
- q["security_groups"] = opts.SecurityGroups
- }
if opts.DeviceID != "" {
q["device_id"] = opts.DeviceID
}
@@ -78,11 +92,8 @@
if opts.Limit != 0 {
q["limit"] = strconv.Itoa(opts.Limit)
}
- if opts.Page != "" {
- q["page"] = opts.Page
- }
- if opts.PerPage != "" {
- q["per_page"] = opts.PerPage
+ if opts.Marker != "" {
+ q["marker"] = opts.Marker
}
if opts.SortKey != "" {
q["sort_key"] = opts.SortKey
@@ -97,6 +108,7 @@
})
}
+// Get retrieves a specific port based on its unique ID.
func Get(c *gophercloud.ServiceClient, id string) (*Port, error) {
var p Port
_, err := perigee.Request("GET", getURL(c, id), perigee.Options{
@@ -112,13 +124,7 @@
return &p, nil
}
-func maybeString(original string) *string {
- if original != "" {
- return &original
- }
- return nil
-}
-
+// CreateOpts represents the attributes used when creating a new port.
type CreateOpts struct {
NetworkID string
Name string
@@ -131,9 +137,11 @@
SecurityGroups []string
}
+// Create accepts a CreateOpts struct and creates a new network using the values
+// provided. You must remember to provide a NetworkID value.
func Create(c *gophercloud.ServiceClient, opts CreateOpts) (*Port, error) {
type port struct {
- NetworkID string `json:"network_id,omitempty"`
+ NetworkID string `json:"network_id"`
Name *string `json:"name,omitempty"`
AdminStateUp *bool `json:"admin_state_up,omitempty"`
MACAddress *string `json:"mac_address,omitempty"`
@@ -149,7 +157,7 @@
// Validate
if opts.NetworkID == "" {
- return nil, ErrNetworkIDRequired
+ return nil, errNetworkIDRequired
}
// Populate request body
@@ -190,6 +198,7 @@
return res.Port, nil
}
+// UpdateOpts represents the attributes used when updating an existing port.
type UpdateOpts struct {
Name string
AdminStateUp *bool
@@ -199,6 +208,8 @@
SecurityGroups []string
}
+// Update accepts a UpdateOpts struct and updates an existing port using the
+// values provided.
func Update(c *gophercloud.ServiceClient, id string, opts UpdateOpts) (*Port, error) {
type port struct {
Name *string `json:"name,omitempty"`
@@ -246,6 +257,7 @@
return res.Port, nil
}
+// Delete accepts a unique ID and deletes the port associated with it.
func Delete(c *gophercloud.ServiceClient, id string) error {
_, err := perigee.Request("DELETE", deleteURL(c, id), perigee.Options{
MoreHeaders: c.Provider.AuthenticatedHeaders(),
diff --git a/openstack/networking/v2/ports/results.go b/openstack/networking/v2/ports/results.go
index 7e90d8d..cddb58d 100644
--- a/openstack/networking/v2/ports/results.go
+++ b/openstack/networking/v2/ports/results.go
@@ -5,11 +5,14 @@
"github.com/rackspace/gophercloud/pagination"
)
+// IP is a sub-struct that represents an individual IP.
type IP struct {
SubnetID string `mapstructure:"subnet_id" json:"subnet_id"`
IPAddress string `mapstructure:"ip_address" json:"ip_address,omitempty"`
}
+// Port represents a Neutron port. See package documentation for a top-level
+// description of what this is.
type Port struct {
// UUID for the port.
ID string `mapstructure:"id" json:"id"`
@@ -45,11 +48,16 @@
BindingVNICType string `mapstructure:"binding:vnic_type" json:"binding:vnic_type"`
}
+// PortPage is the page returned by a pager when traversing over a collection
+// of network ports.
type PortPage struct {
pagination.LinkedPageBase
}
-func (current PortPage) NextPageURL() (string, error) {
+// NextPageURL is invoked when a paginated collection of ports has reached
+// the end of a page and the pager seeks to traverse over a new one. In order
+// to do this, it needs to construct the next page's URL.
+func (p PortPage) NextPageURL() (string, error) {
type resp struct {
Links []struct {
Href string `mapstructure:"href"`
@@ -58,7 +66,7 @@
}
var r resp
- err := mapstructure.Decode(current.Body, &r)
+ err := mapstructure.Decode(p.Body, &r)
if err != nil {
return "", err
}
@@ -76,14 +84,18 @@
return url, nil
}
-func (r PortPage) IsEmpty() (bool, error) {
- is, err := ExtractPorts(r)
+// IsEmpty checks whether a PortPage struct is empty.
+func (p PortPage) IsEmpty() (bool, error) {
+ is, err := ExtractPorts(p)
if err != nil {
return true, nil
}
return len(is) == 0, nil
}
+// ExtractPorts accepts a Page struct, specifically a PortPage struct,
+// and extracts the elements into a slice of Port structs. In other words,
+// a generic collection is mapped into a relevant slice.
func ExtractPorts(page pagination.Page) ([]Port, error) {
var resp struct {
Ports []Port `mapstructure:"ports" json:"ports"`