Commenting for godoc

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),

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

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 {

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)

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)
 }