Add missing documentation

internal/provider/data_rack_controller.go

@@ -9,6 +9,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/gmaw"
 )
 
+// DataRackController provides a lookup for MaaS Rack Controllers
 func DataRackController() *schema.Resource {
 	return &schema.Resource{
 		Read: dataRackControllerRead,

internal/provider/data_subnet.go

@@ -9,6 +9,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas/entity"
 )
 
+// DataSubnet provides a lookup for a MaaS Subnet
 func DataSubnet() *schema.Resource {
 	return &schema.Resource{
 		Read: dataSubnetRead,

internal/provider/provider.go

@@ -9,6 +9,7 @@ import (
 	"github.com/hashicorp/terraform/helper/schema"
 )
 
+// Provider exports a Terraform resource provider and is meant to be called from main().
 func Provider() terraform.ResourceProvider {
 	return &schema.Provider{
 		Schema: map[string]*schema.Schema{

internal/provider/resource_instance.go

@@ -7,6 +7,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas"
 )
 
+// resourceInstance provides a resource that correlates to the MaaS Machine endpoint
 func resourceInstance() *schema.Resource {
 	return &schema.Resource{
 		Create: resourceInstanceCreate,

internal/provider/resource_maas_server.go

@@ -9,6 +9,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/gmaw"
 )
 
+// ResourceServer manages global MaaS configuration options ala the MaaS Server endpoint
 func ResourceServer() *schema.Resource {
 	return &schema.Resource{
 		Create: resourceServerCreate,

internal/provider/resource_network_interface_link.go

@@ -9,6 +9,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/internal/tfschema"
 )
 
+// ResourceNetworkInterfaceLink provides a resource that can be used to manage links between interfaces
 func ResourceNetworkInterfaceLink() *schema.Resource {
 	return &schema.Resource{
 		Create: resourceNetworkInterfaceLinkCreate,

internal/provider/resource_network_interface_physical.go

@@ -6,6 +6,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/internal/tfschema"
 )
 
+// ResourceNetworkInterfacePhysical provides a resource to manage physical interfaces
 func ResourceNetworkInterfacePhysical() *schema.Resource {
 	return &schema.Resource{
 		Create: resourceNetworkInterfacePhysicalCreate,

pkg/api/api.go

@@ -0,0 +1,13 @@
+/*package api defines an interface to each MaaS API endpoint.
+
+Each interface correlates to one endpoint, such as Subnets for the Subnets
+endpoint (ie /subnets) and Subnet for the Subnet endpoint (eg subnets/<subnet_id>).
+API clients are expected to implement these interfaces to provide a normalized way
+of accessing the MaaS API with normalized results (eg the types defined in the
+entity package).
+
+Some endpoint operations require multiple parameters, such as the Rack Controllers
+GET operation, which takes a number of QSP that can be used to filter results. These
+parameters are encapsulated in the params subpackage, providing a quick reference
+for performing API operations.*/
+package api

pkg/api/maas_server.go

@@ -1,5 +1,6 @@
 package api
 
+// MAASServer represents the MaaS Server endpoint for changing global configuration settings
 type MAASServer interface {
 	Get(name string) (value string, err error)
 	Post(name, value string) error

pkg/api/rack_controllers.go

@@ -5,6 +5,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas/entity"
 )
 
+// RackControllers represents the MaaS Rack Controllers endpoint
 type RackControllers interface {
 	Get(*params.RackControllerSearch) ([]entity.RackController, error)
 }

pkg/api/subnet.go

@@ -6,6 +6,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas/entity/subnet"
 )
 
+// Subnet represents the MaaS Subnet endpoint
 type Subnet interface {
 	Delete(id int) error
 	Get(id int) (*entity.Subnet, error)

pkg/api/subnets.go

@@ -5,6 +5,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas/entity"
 )
 
+// Subnets represents the MaaS Subnets endpoint
 type Subnets interface {
 	Get() ([]entity.Subnet, error)
 	Post(*params.Subnet) (*entity.Subnet, error)

pkg/api/vlans.go

@@ -5,6 +5,7 @@ import (
 	"github.com/roblox/terraform-provider-maas/pkg/maas/entity"
 )
 
+// VLANs represents the MaaS Vlans endpoint
 type VLANs interface {
 	Get(fabricID int) ([]entity.VLAN, error)
 	Post(fabricID int, params *params.VLAN) (*entity.VLAN, error)

pkg/maas/entity/entity.go

@@ -0,0 +1,11 @@
+/*package entity defines types for the MaaS API endpoints' return types.
+
+Each endpoint returns JSON that describes the object it represents. For example,
+GETting the Subnets endpoint will return an array of Subnet, while GETting the
+Subnet endpoint (ie subnets/<subnet_id>) will return one Subnet.
+
+Some endpoints expose operations that return metadata about the object, such as as
+Subnet's GetStatistics(), which contains statistics about the subnet, but does not
+actually describe the subnet: these alternative types can be found in subpackages
+named after the endpoint.*/
+package entity

pkg/maas/entity/subnet/ip_address.go

@@ -4,6 +4,7 @@ import (
 	"net"
 )
 
+// IPAddress represents an IP address from a Subnet's GetIPAddresses()
 type IPAddress struct {
 	IP          net.IP      `json:"ip,omitempty"`
 	AllocType   int         `json:"alloc_type,omitempty"`
@@ -13,6 +14,8 @@ type IPAddress struct {
 	User        string      `json:"user,omitempty"`
 }
 
+// NodeSummary represents the optional node_summary from GetIPAddresses().
+// This type should not be used directly.
 type NodeSummary struct {
 	SystemID    string `json:"system_id,omitempty"`
 	NodeType    int    `json:"node_type,omitempty"`

pkg/maas/entity/subnet/ip_range.go

@@ -2,6 +2,7 @@ package subnet
 
 import "net"
 
+// IPRange represents an IP range from a Subnet's GetUnreservedIPRanges()
 type IPRange struct {
 	Start        net.IP `json:"start,omitempty"`
 	End          net.IP `json:"end,omitempty"`

pkg/maas/entity/subnet/reserved_ip_range.go

@@ -1,5 +1,6 @@
 package subnet
 
+// ReservedIPRange represents an IP range from a Subnet's GetReservedIPRanges()
 type ReservedIPRange struct {
 	IPRange
 	Purpose []string `json:"purpose,omitempty"`

pkg/maas/entity/subnet/statistics.go

@@ -2,6 +2,7 @@ package subnet
 
 import "net"
 
+// Statistics represents a Subnet's GetStatistics()
 type Statistics struct {
 	NumAvailable     int     `json:"num_available,omitempty"`
 	LargestAvailable int     `json:"largest_available,omitempty"`

pkg/maas/maas.go

@@ -135,7 +135,3 @@ func ToQSP(t interface{}) url.Values {
 	}
 	return qsp
 }
-
-func ToSnakeCase(s string) string {
-	return s
-}

pkg/maas/machines.go

@@ -3,12 +3,12 @@ package maas
 // Machines represents the Machines endpoint
 type Machines []Machine
 
-// MachinesManager
+// MachinesManager provides locking and management capabilities for Machines
 type MachinesManager struct {
 	client MachinesFetcher
 }
 
-// NewMachineManager
+// NewMachineManager creates a new MachinesManager
 func NewMachinesManager(client MachinesFetcher) *MachinesManager {
 	return &MachinesManager{client: client}
 }