better names and comments

check/abuseipdb.go

@@ -14,6 +14,7 @@ const abuseIPDBMaxAgeInDays = "90"
 
 var abuseIPDBUrl = "https://api.abuseipdb.com/api/v2/check"
 
+// abuseIPDB represents JSON data returned by the AbuseIPDB API.
 type abuseIPDB struct {
 	IsWhitelisted        bool          `json:"isWhitelisted"`
 	AbuseConfidenceScore int           `json:"abuseConfidenceScore"`
@@ -37,15 +38,15 @@ func (a abuseIPDB) Json() ([]byte, error) {
 }
 
 // AbuseIPDB uses api.abuseipdb.com to get generic information about ipaddr and
-// see if the ipaddr has been reported as malicious.
+// to see if the ipaddr has been reported as malicious.
 func AbuseIPDB(ipaddr net.IP) (checkip.Result, error) {
 	result := checkip.Result{Name: "abuseipdb.com", Type: checkip.TypeInfoSec}
 
 	apiKey, err := getConfigValue("ABUSEIPDB_API_KEY")
 	if err != nil {
 		return result, newCheckError(err)
 	}
-	if apiKey == "" {
+	if apiKey == "" { // we don't consider missing to be an error
 		return result, nil
 	}
 
@@ -60,19 +61,18 @@ func AbuseIPDB(ipaddr net.IP) (checkip.Result, error) {
 		"maxAgeInDays": abuseIPDBMaxAgeInDays,
 	}
 
-	var data struct {
-		AbuseIPDB abuseIPDB `json:"data"`
+	var response struct {
+		Data abuseIPDB `json:"data"`
 	}
 	// docs.abuseipdb.com/#check-endpoint
-	if err := defaultHttpClient.GetJson(abuseIPDBUrl, headers, queryParams, &data); err != nil {
+	if err := defaultHttpClient.GetJson(abuseIPDBUrl, headers, queryParams, &response); err != nil {
 		return result, newCheckError(err)
 	}
 
-	result.Info = data.AbuseIPDB
-	result.Malicious = data.AbuseIPDB.TotalReports > 0 &&
-		!data.AbuseIPDB.IsWhitelisted &&
-		data.AbuseIPDB.AbuseConfidenceScore > 25
+	result.Info = response.Data
+	result.Malicious = response.Data.TotalReports > 0 &&
+		!response.Data.IsWhitelisted &&
+		response.Data.AbuseConfidenceScore > 25
 
 	return result, nil
-
 }

check/error.go

@@ -6,12 +6,14 @@ import (
 	"strings"
 )
 
-// checkError is an error returned by a check.
+// checkError is an error that should be returned by a check.
 type checkError struct {
 	err       error  // might contain secrets, like API keys
-	ErrString string `json:"error"` // secrets redacted
+	ErrString string `json:"error"` // secrets redacted, ok to print
 }
 
+// newCheckError returns an error that contains caller name and has potential
+// secrets redacted.
 func newCheckError(err error) *checkError {
 	callerName := "unknownCaller"
 	pc, _, _, ok := runtime.Caller(1)

checkip.go

@@ -34,10 +34,10 @@ type Check func(ipaddr net.IP) (Result, error)
 
 // Result is the information provided by a Check.
 type Result struct {
-	Name      string `json:"name"`      // check name; max 15 chars
+	Name      string `json:"name"`      // check name, max 15 chars
 	Type      Type   `json:"type"`      // check type
-	Info      Info   `json:"info"`      // provided by TypeInfo and TypeInfoSec check
-	Malicious bool   `json:"malicious"` // provided by TypeSec check
+	Malicious bool   `json:"malicious"` // provided by TypeSec check type
+	Info      Info   `json:"info"`
 }
 
 // Info is generic information provided by a TypeInfo or TypeInfoSec Check.