From e79e7e33f227613ac782e2f3a7f8e6f8e35c8ac5 Mon Sep 17 00:00:00 2001 From: Mike Cheng Date: Mon, 4 May 2015 20:20:11 -0400 Subject: [PATCH] Commenting for godoc --- api/api.go | 19 +++++++++++++------ api/config.go | 10 ++++++++++ dyndns/daemon.go | 4 +++- dyndns/external.go | 8 +++++++- log/log.go | 4 ++++ 5 files changed, 37 insertions(+), 8 deletions(-) diff --git a/api/api.go b/api/api.go index ff65b9f..ba41cea 100644 --- a/api/api.go +++ b/api/api.go @@ -1,3 +1,5 @@ +// Package api provides a basic interface for dealing +// with Name.com DNS API's. package api import ( @@ -15,12 +17,14 @@ const ( devUrl = "https://api.dev.name.com/" ) +// Contains details required to access the Name.com API. type API struct { baseUrl string username string token string } +// A Name.com DNS record. type DNSRecord struct { RecordId string `json:"record_id"` Name string `json:"name"` @@ -35,10 +39,8 @@ type resultResponse struct { Message string `json:"message"` } -// Constructs a new Name.com API -// -// If dev = true, then the API uses the development -// API, instead of the production API. +// Constructs a new Name.com API. If dev is true, then +// the API uses the development API, instead of the production API. func NewNameAPI(username, token string, dev bool) API { a := API{username: username, token: token} @@ -51,7 +53,7 @@ func NewNameAPI(username, token string, dev bool) API { return a } -// Constructs a new Name.com API from a configuration +// Constructs a new Name.com API from a configuration. func NewAPIFromConfig(c Config) API { return NewNameAPI(c.Username, c.Token, c.Dev) } @@ -75,6 +77,9 @@ func (api API) performRequest(method, url string, body io.Reader) (response []by return ioutil.ReadAll(resp.Body) } +// Create a DNS record for a given domain. The hostname is +// specified in the DNSRecord under name, and should not +// include the domain. func (api API) CreateDNSRecord(domain string, record DNSRecord) error { b, err := json.Marshal(record) if err != nil { @@ -105,6 +110,8 @@ func (api API) CreateDNSRecord(domain string, record DNSRecord) error { return nil } +// Deletes a DNS record for a given domain. The recordId can +// be retreived from GetDNSRecords. func (api API) DeleteDNSRecord(domain, recordId string) error { var body struct { RecordId string `json:"record_id"` @@ -141,7 +148,7 @@ func (api API) DeleteDNSRecord(domain, recordId string) error { } // Returns a slice of DNS records associated with a given domain. -func (api API) GetRecords(domain string) (records []DNSRecord, err error) { +func (api API) GetDNSRecords(domain string) (records []DNSRecord, err error) { resp, err := api.performRequest( "GET", fmt.Sprintf("%s%s%s", api.baseUrl, "api/dns/list/", domain), diff --git a/api/config.go b/api/config.go index 37fcd07..d2e3905 100644 --- a/api/config.go +++ b/api/config.go @@ -5,6 +5,14 @@ import ( "io/ioutil" ) +// Each configuration should represent a specifc domain. +// A domain can have multiple hostnames, and the hostnames +// that should be automaticall updated are in Hostnames. +// If the root domain is to be managed, an empty hostname +// should be added to the Hostnames slice. +// +// The interval is the polling time (in seconds) for +// daemon mode. type Config struct { Dev bool `json:"dev"` Domain string `json:"domain"` @@ -14,6 +22,8 @@ type Config struct { Username string `json:"username"` } +// Loads configurations from a file. The configuration +// is stored as an array of JSON serialized Config structs. func LoadConfigs(path string) ([]Config, error) { var configs struct { Configs []Config diff --git a/dyndns/daemon.go b/dyndns/daemon.go index 09947ac..f1a92fb 100644 --- a/dyndns/daemon.go +++ b/dyndns/daemon.go @@ -1,3 +1,5 @@ +// Package dyndns provides a tool for running a +// dynamic dns updating service. package dyndns import ( @@ -42,7 +44,7 @@ func runConfig(c api.Config, daemon bool) { // 1 per hostname with the associated domain. // If the content is not the current IP, then // update it. - records, err := a.GetRecords(c.Domain) + records, err := a.GetDNSRecords(c.Domain) if err != nil { log.Logger.Printf("Failed to retreive records for%s\n", c.Domain) if daemon { diff --git a/dyndns/external.go b/dyndns/external.go index 6320275..e9ac53f 100644 --- a/dyndns/external.go +++ b/dyndns/external.go @@ -6,6 +6,9 @@ import ( "net/http" ) +// Urls contains a set of mirrors in which a +// raw IP string can be retreived. It is exported +// for the intent of modification. var ( Urls = []string{"http://myexternalip.com/raw"} ) @@ -25,7 +28,10 @@ func tryMirror(url string) (string, error) { return string(contents), nil } -// Retrieves the external facing IP Address +// Retrieves the external facing IP Address. +// If multiple mirrors are provided in Urls, +// it will try each one (in order), should +// preceding mirrors fail. func GetExternalIP() (string, error) { for _, url := range Urls { resp, err := tryMirror(url) diff --git a/log/log.go b/log/log.go index 050fb52..bdb4a14 100644 --- a/log/log.go +++ b/log/log.go @@ -1,3 +1,4 @@ +// Package log provides a basic global logger for name-dyndns. package log import ( @@ -5,8 +6,11 @@ import ( "log" ) +// Global logger. var Logger *log.Logger +// Initialize the logger with a specific io.Writer. +// This function is generally called near startup. func Init(writer io.Writer) { Logger = log.New(writer, "", log.Ldate|log.Ltime) }