git » spf » commit d29dbf3

Document that check functions can return non-nil error on success

author Alberto Bertogli
2021-05-01 00:19:11 UTC
committer Alberto Bertogli
2021-05-01 00:37:54 UTC
parent 622b60db715ebb86d3521cae4c5d736a658f2126
Document that check functions can return non-nil error on success

The behaviour of returning non-nil error on a success run is
non-ideomatic and can be surprising.

This patch adds some documentation to the Check functions, so it is
clear and visible.

Thanks to Christian Schneider <christian.schneider@androidloves.me> for
reporting this.
spf.go +8 -0 
diff --git a/spf.go b/spf.go
index 38718bf..8b8c6a9 100644
--- a/spf.go
+++ b/spf.go
@@ -118,6 +118,10 @@ type Option func(*resolution)
 // usage is not recommended, but remains supported for backwards
 // compatibility.
 //
+// The function returns a Result, which corresponds with the SPF result for
+// the check as per RFC, as well as an error for debugging purposes. Note that
+// the error may be non-nil even on successful checks.
+//
 // Reference: https://tools.ietf.org/html/rfc7208#section-4
 //
 // Deprecated: use CheckHostWithSender instead.
@@ -140,6 +144,10 @@ func CheckHost(ip net.IP, domain string) (Result, error) {
 // The `opts` optional parameter can be used to adjust some specific
 // behaviours, such as the maximum number of DNS lookups allowed.
 //
+// The function returns a Result, which corresponds with the SPF result for
+// the check as per RFC, as well as an error for debugging purposes. Note that
+// the error may be non-nil even on successful checks.
+//
 // Reference: https://tools.ietf.org/html/rfc7208#section-4
 func CheckHostWithSender(ip net.IP, helo, sender string, opts ...Option) (Result, error) {
 	_, domain := split(sender)