Improve comments

Update several function comments to add more detail.
Update direct dependency package versions.

go.mod

@@ -3,6 +3,6 @@ module github.com/beevik/ntp
 go 1.13
 
 require (
-	github.com/stretchr/testify v1.8.2
-	golang.org/x/net v0.9.0
+	github.com/stretchr/testify v1.8.4
+	golang.org/x/net v0.10.0
 )

go.sum

@@ -8,8 +8,8 @@ github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSS
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
-github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
@@ -19,8 +19,8 @@ golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
-golang.org/x/net v0.9.0 h1:aWJ/m6xSmxWBx+V0XRHTlrYrPG56jKsLdTFmsSsCzOM=
-golang.org/x/net v0.9.0/go.mod h1:d48xBJpPfHeWQsugry2m+kC02ZBRGRgulfHnEXEuWns=
+golang.org/x/net v0.10.0 h1:X2//UzNDwYmtCLn7To6G58Wr6f5ahEAQgKNzv9Y951M=
+golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -30,12 +30,12 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
-golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.8.0 h1:EBmGv8NaZBZTWvrbjNoL6HVt+IVy3QDQpJs7VRIw3tU=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
-golang.org/x/term v0.7.0/go.mod h1:P32HKFT3hSsZrRxla30E9HqToFYAQPCMs/zFMBUFqPY=
+golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=

ntp.go

@@ -1,4 +1,4 @@
-// Copyright 2015-2017 Brett Vickers.
+// Copyright 2015-2023 Brett Vickers.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
@@ -160,31 +160,36 @@ func (m *msg) getLeap() LeapIndicator {
 	return LeapIndicator((m.LiVnMode >> 6) & 0x03)
 }
 
-// DialFunc is a function that connects to the remote network address and port
-// from the local network address and port when using QueryWithOptions.
-type DialFunc func(laddr string, lport int, raddr string, rport int) (net.Conn, error)
-
-// QueryOptions contains the list of configurable options that may be used
-// with the QueryWithOptions function.
+// dialFn is a function used to override the QueryWithOptions function's
+// default network "dialing" behavior. It creates a connection to a remote
+// network endpoint (raddr + rport) from a local network endpoint (laddr +
+// lport). The local address 'laddr' comes from the 'LocalAddress' specified
+// in QueryOptions. The local port 'lport' is always zero. The remote address
+// 'raddr' comes from the QueryWithOptions host parameter. The remote port
+// 'rport' comes from the 'Port' specified in QueryOptions.
+type dialFn func(laddr string, lport int, raddr string, rport int) (net.Conn, error)
+
+// QueryOptions contains configurable options used by the QueryWithOptions
+// function.
 type QueryOptions struct {
-	Timeout      time.Duration // defaults to 5 seconds
+	Timeout      time.Duration // connection timeout, defaults to 5 seconds
 	Version      int           // NTP protocol version, defaults to 4
-	LocalAddress string        // IP address to use for the client address
-	Port         int           // Server port, defaults to 123
+	LocalAddress string        // address to use for the local system
+	Port         int           // remote server port, defaults to 123
 	TTL          int           // IP TTL to use, defaults to system default
-	Dial         DialFunc      // Overrides the use of the default UDP dialer
+	Dial         dialFn        // overrides the default UDP dialer
 }
 
 // A Response contains time data, some of which is returned by the NTP server
-// and some of which is calculated by the client.
+// and some of which is calculated by this client.
 type Response struct {
 	// Time is the transmit time reported by the server just before it
 	// responded to the client's NTP query.
 	Time time.Time
 
-	// ClockOffset is the estimated offset of the client clock relative to
-	// the server. Add this to the client's system clock time to obtain a
-	// more accurate time.
+	// ClockOffset is the estimated offset of the local system clock relative
+	// to the server's clock. Add this value to subsequent local system time
+	// measurements in order to obtain a more accurate time.
 	ClockOffset time.Duration
 
 	// RTT is the measured round-trip-time delay estimate between the client
@@ -286,9 +291,9 @@ func (r *Response) Validate() error {
 	return nil
 }
 
-// Query returns a response from the remote NTP server host. It contains
-// the time at which the server transmitted the response as well as other
-// useful information about the time and the remote server.
+// Query returns a response from the remote NTP server at address 'host'. The
+// response contains the time at which the server responded to the query as
+// well as other useful information about the time and the remote server.
 func Query(host string) (*Response, error) {
 	return QueryWithOptions(host, QueryOptions{})
 }
@@ -303,9 +308,9 @@ func QueryWithOptions(host string, opt QueryOptions) (*Response, error) {
 	return parseTime(m, now), nil
 }
 
-// Time returns the current time using information from a remote NTP server.
-// It uses version 4 of the NTP protocol. On error, it returns the local
-// system time.
+// Time returns the current local time using information returned from the
+// remote NTP server at address 'host'. It uses version 4 of the NTP protocol.
+// On error, it returns the local system time.
 func Time(host string) (time.Time, error) {
 	r, err := Query(host)
 	if err != nil {
@@ -324,6 +329,9 @@ func Time(host string) (time.Time, error) {
 // getTime performs the NTP server query and returns the response message
 // along with the local system time it was received.
 func getTime(host string, opt QueryOptions) (*msg, ntpTime, error) {
+	if opt.Timeout == 0 {
+		opt.Timeout = defaultTimeout
+	}
 	if opt.Version == 0 {
 		opt.Version = defaultNtpVersion
 	}
@@ -337,6 +345,7 @@ func getTime(host string, opt QueryOptions) (*msg, ntpTime, error) {
 		opt.Dial = defaultDial
 	}
 
+	// Connect to the remote server.
 	con, err := opt.Dial(opt.LocalAddress, 0, host, opt.Port)
 	if err != nil {
 		return nil, 0, err
@@ -353,9 +362,6 @@ func getTime(host string, opt QueryOptions) (*msg, ntpTime, error) {
 	}
 
 	// Set a timeout on the connection.
-	if opt.Timeout == 0 {
-		opt.Timeout = defaultTimeout
-	}
 	con.SetDeadline(time.Now().Add(opt.Timeout))
 
 	// Allocate a message to hold the response.
@@ -394,16 +400,10 @@ func getTime(host string, opt QueryOptions) (*msg, ntpTime, error) {
 		return nil, 0, err
 	}
 
-	// Keep track of the time the response was received.
+	// Keep track of the time the response was received. As of go 1.9,
+	// time.Since assumes a monotonic clock, so delta cannot be less than
+	// zero.
 	delta := time.Since(xmitTime)
-	if delta < 0 {
-		// The local system may have had its clock adjusted since it
-		// sent the query. In go 1.9 and later, time.Since ensures
-		// that a monotonic clock is used, so delta can never be less
-		// than zero. In versions before 1.9, a monotonic clock is
-		// not used, so we have to check.
-		return nil, 0, errors.New("client clock ticked backwards")
-	}
 	recvTime := toNtpTime(xmitTime.Add(delta))
 
 	// Check for invalid fields.

ntp_test.go

@@ -1,4 +1,4 @@
-// Copyright 2015-2017 Brett Vickers.
+// Copyright 2015-2023 Brett Vickers.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.