Types: Add comments describing the fields, types, packages and functions

3 files changed, 104 insertions, 12 deletions

diff --git a/types/discovery/discovery.go b/types/discovery/discovery.go
index 390cb43..5f54721 100644
--- a/types/discovery/discovery.go
+++ b/types/discovery/discovery.go
@@ -1,3 +1,4 @@
+// package discovery defines the public types that have to deal with discovery
 package discovery
 
 import (
@@ -5,29 +6,68 @@ import (
 	"time"
 )
 
+// Organizations is the type that defines the upstream discovery format for the list of organizations
 // TODO: Discovery here is the same as the upstream discovery format, should we separate this as well?
 // Defined in URL: "https://disco.eduvpn.org/v2/organization_list.json"
 type Organizations struct {
+	// Version is the version field. The Go library internally already checks for rollbacks, you can use this for logging
 	Version   uint64         `json:"v"`
+	// List is the list/slice of organizations. Omitted if none are there
 	List      []Organization `json:"organization_list,omitempty"`
+	// Timestamp is a timestamp that is internally used by the Go library to keep track of when the organizations was last updated
+	// You can also use this for logging
 	Timestamp time.Time      `json:"go_timestamp"`
 }
 
+// Organization is the type that defines the upstream discovery format for a single organization
 type Organization struct {
+	// DisplayName is the map of strings from language tags to display names
+	// Omitted if none is defined
 	DisplayName        MapOrString `json:"display_name,omitempty"`
+	// OrgID is the organization ID for the server
 	OrgID              string      `json:"org_id"`
+	// SecureInternetHome is the secure internet home server that belongs to this organization
+	// Omitted if none is defined
 	SecureInternetHome string      `json:"secure_internet_home,omitempty"`
+	// KeywordList is the list of keywords
+	// Omitted if none is defined
 	KeywordList        MapOrString `json:"keyword_list,omitempty"`
 }
 
-// Structs that define the json format for
+// Servers is the type that defines the upstream discovery format for the list of servers
 // url: "https://disco.eduvpn.org/v2/server_list.json"
 type Servers struct {
+	// Version is the version field in discovery. The Go library already checks for rollbacks, use this for logging
 	Version   uint64    `json:"v"`
+	// List is the actual list of servers, omitted from the JSON if empty
 	List      []Server  `json:"server_list,omitempty"`
+	// Timestamp is a timestamp that is internally used by the Go library to keep track of when the organizations was last updated
+	// You can also use this for logging
 	Timestamp time.Time `json:"go_timestamp"`
 }
 
+// Server is a signle discovery server
+type Server struct {
+	// AuthenticationURLTemplate is the template to be used for authentication to skip WAYF
+	AuthenticationURLTemplate string      `json:"authentication_url_template"`
+	// BaseURL is the base URL of the server which is used as an identifier for the server by the Go library
+	BaseURL                   string      `json:"base_url"`
+	// CountryCode is the country code for the server in case of secure internet, e.g. NL
+	CountryCode               string      `json:"country_code"`
+	// DisplayName is the display name of the server, omitted if empty
+	DisplayName               MapOrString `json:"display_name,omitempty"`
+	// DisplayName are the keywords of the server, omitted if empty
+	KeywordList               MapOrString `json:"keyword_list,omitempty"`
+	// PublicKeyList are the public keys of the server. Currently not used in this lib but returned by the upstream discovery server
+	PublicKeyList             []string    `json:"public_key_list"`
+	// Type is the type of the server, "secure_internet" or "institute_access"
+	Type                      string      `json:"server_type"`
+	// SupportContact is the list/slice of support contacts
+	SupportContact            []string    `json:"support_contact"`
+}
+
+// MapOrString is a custom type as the upstream discovery format is a map or a value.
+// This library always marshals the data as a map and then makes sure unmarshalling also gives a map
 type MapOrString map[string]string
 
 // The display name can either be a map or a string in the server list
@@ -52,14 +92,3 @@ func (displayName *MapOrString) UnmarshalJSON(data []byte) error {
 	}
 	return err
 }
-
-type Server struct {
-	AuthenticationURLTemplate string      `json:"authentication_url_template"`
-	BaseURL                   string      `json:"base_url"`
-	CountryCode               string      `json:"country_code"`
-	DisplayName               MapOrString `json:"display_name,omitempty"`
-	KeywordList               MapOrString `json:"keyword_list,omitempty"`
-	PublicKeyList             []string    `json:"public_key_list"`
-	Type                      string      `json:"server_type"`
-	SupportContact            []string    `json:"support_contact"`
-}
diff --git a/types/protocol/protocol.go b/types/protocol/protocol.go
index 6e003f7..e35de2b 100644
--- a/types/protocol/protocol.go
+++ b/types/protocol/protocol.go
@@ -1,5 +1,7 @@
+// package protocol contains hte public type that have to do with VPN protocols
 package protocol
 
+// Protocol defines an 'enumeration' of protocols
 type Protocol int8
 
 const (
@@ -11,6 +13,7 @@ const (
 	WireGuard
 )
 
+// New creates a new protocol type from a string
 func New(p string) Protocol {
 	switch p {
 	case "openvpn":
diff --git a/types/server/server.go b/types/server/server.go
index cdc1610..9747ebf 100644
--- a/types/server/server.go
+++ b/types/server/server.go
@@ -1,73 +1,133 @@
+// package server defines public types that have to deal with the VPN server
 package server
 
 import "github.com/eduvpn/eduvpn-common/types/protocol"
 
+// Type gives the type of server
 type Type int8
 
 const (
+	// TypeUnknown means the server is unknown
 	TypeUnknown Type = iota
+	// TypeInstituteAccess means the server is of type Institute Access
 	TypeInstituteAccess
+	// TypeSecureInternet means the server is of type Secure Internet
 	TypeSecureInternet
+	// TypeCustom means the server is of type Custom Server
 	TypeCustom
 )
 
+// Expiry is the struct that gives the time at which certain expiry elements should be shown
 type Expiry struct {
+	// StartTime is the start time of the VPN in Unix
 	StartTime         int64   `json:"start_time"`
+	// EndTime is the end time of the VPN in Unix.
 	EndTime           int64   `json:"end_time"`
+	// ButtonTime is the Unix time at which to start showing the renew button in the UI
 	ButtonTime        int64   `json:"button_time"`
+	// CountdownTime is the Unix time at which to start showing more detailed countdown timer.
+	// E.g. first start with days (7 days left), and when the current time is after this time, show e.g. 9 minutes and 59 seconds
 	CountdownTime     int64   `json:"countdown_time"`
+	// NotificationTimes is the slice/list of times at which to show a notification that the VPN is about to expire
 	NotificationTimes []int64 `json:"notification_times"`
 }
 
+// Profile is the profile for the VPN, to show in the UI where the user can switch to it to get a different VPN configuration
 type Profile struct {
+	// DisplayName is the display name of the profile as a map
+	// It is a map where country codes are mapped to names, this is to be consistent with the format of other display names
+	// E.g. {"en": "Default Profile"}
+	// If this is empty, the field is omitted from the JSON
 	DisplayName map[string]string   `json:"display_name,omitempty"`
+	// Protocols is the list of protocols that this profile supports
 	Protocols   []protocol.Protocol `json:"supported_protocols"`
 }
 
+// Profiles is the map of profiles with the current defined
 type Profiles struct {
+	// Map, the map of profiles from profile ID to the profile contents
+	// If this is empty, the field is omitted from the JSON
 	Map     map[string]Profile `json:"map,omitempty"`
+	// Current is the current profile ID that is defined
 	Current string             `json:"current"`
 }
 
+// Tokens are the OAuth tokens for the server
 type Tokens struct {
+	// Access is the access token
 	Access  string `json:"access_token"`
+	// Refresh is the refresh token
 	Refresh string `json:"refresh_token"`
+	// Expires is the Unix timestamp when the token expires
 	Expires int64  `json:"expires_in"`
 }
 
+// Server is the basic type for a server. This is the base for secure internet and institute access. Custom servers are equal to this type
 type Server struct {
+	// DisplayName is the map from language tags to display name. If this is empty, the field is omitted from the JSON
 	DisplayName map[string]string `json:"display_name,omitempty"`
+	// Identifier is the Base URL for Institute Access and Custom Server. For Secure Internet this is the organization ID
+	// This identifier should be passed to the Go library for e.g. getting a config
 	Identifier  string            `json:"identifier"`
+	// Profiles is the profiles that this server has defined
+	// It could be that this is empty if the library has not discovered the profiles just yet
 	Profiles    Profiles          `json:"profiles"`
 }
 
+// Institute defines an institute access server
 type Institute struct {
+	// Server is the embedded server struct
 	Server
+	// Delisted is a boolean that indicates whether or not this server is delisted from discovery
+	// If it is, the UI should show a warning symbol or move the server to a new category, which is up to the client
 	Delisted bool `json:"delisted"`
 }
 
+// SecureInternet is a secure internet server
 type SecureInternet struct {
+	// Server is the embedded server struct
 	Server
+	// CountryCode is the country code of the currently configured location, e.g. "nl"
 	CountryCode string `json:"country_code"`
+	// Delisted is a boolean that indicates whether or not this server is delisted from discovery
+	// If it is, the UI should show a warning symbol or move the server to a new category, which is up to the client
 	Delisted    bool   `json:"delisted"`
 }
 
+// List is the list of servers
 type List struct {
+	// Institutes is the list/slice of institute access servers. If none are defined, this is omitted in the JSON
 	Institutes     []Institute     `json:"institute_access_servers,omitempty"`
+	// Secure Internet is the secure internet server if any. If none is there, it is omitted in the JSON
 	SecureInternet *SecureInternet `json:"secure_internet_server,omitempty"`
+	// Custom is the list/slice of custom servers. If none are defined, this is omitted in the JSON
 	Custom         []Server       `json:"custom_servers,omitempty"`
 }
 
+// Configuration is the configuration that you get back when you call the get config function
 type Configuration struct {
+	// VPNConfig is the VPN Configuration, a WireGuard or OpenVPN Configuration
 	VPNConfig      string            `json:"config"`
+	// Protocol defines which protocol the configuration is for, OpenVPN or WireGuard
 	Protocol       protocol.Protocol `json:"protocol"`
+	// DefaultGateway is a boolean that indicates whether or not this configuration should be configured as a default gateway
 	DefaultGateway bool              `json:"default_gateway"`
+	// Tokens is the updated tokens that we get back from the VPN configuration
+	// They should be used by the client to save them in e.g. the keyring
 	Tokens         Tokens            `json:"tokens"`
 }
 
+// Current is the struct that defines the current server
+// It has different fields where only two are always filled in
 type Current struct {
+	// The following three are mutually exclusive
+
+	// Institute is the institute access server if any, if none is there this field is omitted in the JSON
 	Institute      *Institute      `json:"institute_access_server,omitempty"`
+	// Secure Internet is the secure internet server if any, if none is there this field is omitted in the JSON
 	SecureInternet *SecureInternet `json:"secure_internet_server,omitempty"`
+	// Custom is the custom server if any, if none is there this field is omitted in the JSON
 	Custom         *Server        `json:"custom_server,omitempty"`
+	// Type is the type of server that is there to check which of the three types should be non-nil
 	Type           Type            `json:"server_type"`
 }