Improve argument/return names for better docs (#96)

This change is a renaming with no functional changes.

It includes the following renames:
 * `val` for arguments that replace the atomic value (e.g., `Store`).
 * `delta` for arguments that offset the atomic value (e.g., `Add`).
 * `old`, `new` for arguments to `CAS`.
 * `old` named return from `Swap`.
 * `swapped` for named return from `CAS`.

This also matches the names used in the stdlib atomic interface:
https://golang.org/pkg/sync/atomic/

bool.go

@@ -36,10 +36,10 @@ type Bool struct {
 var _zeroBool bool
 
 // NewBool creates a new Bool.
-func NewBool(v bool) *Bool {
+func NewBool(val bool) *Bool {
 	x := &Bool{}
-	if v != _zeroBool {
-		x.Store(v)
+	if val != _zeroBool {
+		x.Store(val)
 	}
 	return x
 }
@@ -50,19 +50,19 @@ func (x *Bool) Load() bool {
 }
 
 // Store atomically stores the passed bool.
-func (x *Bool) Store(v bool) {
-	x.v.Store(boolToInt(v))
+func (x *Bool) Store(val bool) {
+	x.v.Store(boolToInt(val))
 }
 
 // CAS is an atomic compare-and-swap for bool values.
-func (x *Bool) CAS(o, n bool) bool {
-	return x.v.CAS(boolToInt(o), boolToInt(n))
+func (x *Bool) CAS(old, new bool) (swapped bool) {
+	return x.v.CAS(boolToInt(old), boolToInt(new))
 }
 
 // Swap atomically stores the given bool and returns the old
 // value.
-func (x *Bool) Swap(o bool) bool {
-	return truthy(x.v.Swap(boolToInt(o)))
+func (x *Bool) Swap(val bool) (old bool) {
+	return truthy(x.v.Swap(boolToInt(val)))
 }
 
 // MarshalJSON encodes the wrapped bool into JSON.

bool_ext.go

@@ -38,7 +38,7 @@ func boolToInt(b bool) uint32 {
 }
 
 // Toggle atomically negates the Boolean and returns the previous value.
-func (b *Bool) Toggle() bool {
+func (b *Bool) Toggle() (old bool) {
 	for {
 		old := b.Load()
 		if b.CAS(old, !old) {

duration.go

@@ -37,10 +37,10 @@ type Duration struct {
 var _zeroDuration time.Duration
 
 // NewDuration creates a new Duration.
-func NewDuration(v time.Duration) *Duration {
+func NewDuration(val time.Duration) *Duration {
 	x := &Duration{}
-	if v != _zeroDuration {
-		x.Store(v)
+	if val != _zeroDuration {
+		x.Store(val)
 	}
 	return x
 }
@@ -51,19 +51,19 @@ func (x *Duration) Load() time.Duration {
 }
 
 // Store atomically stores the passed time.Duration.
-func (x *Duration) Store(v time.Duration) {
-	x.v.Store(int64(v))
+func (x *Duration) Store(val time.Duration) {
+	x.v.Store(int64(val))
 }
 
 // CAS is an atomic compare-and-swap for time.Duration values.
-func (x *Duration) CAS(o, n time.Duration) bool {
-	return x.v.CAS(int64(o), int64(n))
+func (x *Duration) CAS(old, new time.Duration) (swapped bool) {
+	return x.v.CAS(int64(old), int64(new))
 }
 
 // Swap atomically stores the given time.Duration and returns the old
 // value.
-func (x *Duration) Swap(o time.Duration) time.Duration {
-	return time.Duration(x.v.Swap(int64(o)))
+func (x *Duration) Swap(val time.Duration) (old time.Duration) {
+	return time.Duration(x.v.Swap(int64(val)))
 }
 
 // MarshalJSON encodes the wrapped time.Duration into JSON.

duration_ext.go

@@ -25,13 +25,13 @@ import "time"
 //go:generate bin/gen-atomicwrapper -name=Duration -type=time.Duration -wrapped=Int64 -pack=int64 -unpack=time.Duration -cas -swap -json -imports time -file=duration.go
 
 // Add atomically adds to the wrapped time.Duration and returns the new value.
-func (d *Duration) Add(n time.Duration) time.Duration {
-	return time.Duration(d.v.Add(int64(n)))
+func (d *Duration) Add(delta time.Duration) time.Duration {
+	return time.Duration(d.v.Add(int64(delta)))
 }
 
 // Sub atomically subtracts from the wrapped time.Duration and returns the new value.
-func (d *Duration) Sub(n time.Duration) time.Duration {
-	return time.Duration(d.v.Sub(int64(n)))
+func (d *Duration) Sub(delta time.Duration) time.Duration {
+	return time.Duration(d.v.Sub(int64(delta)))
 }
 
 // String encodes the wrapped value as a string.

error.go

@@ -32,10 +32,10 @@ type Error struct {
 var _zeroError error
 
 // NewError creates a new Error.
-func NewError(v error) *Error {
+func NewError(val error) *Error {
 	x := &Error{}
-	if v != _zeroError {
-		x.Store(v)
+	if val != _zeroError {
+		x.Store(val)
 	}
 	return x
 }
@@ -46,6 +46,6 @@ func (x *Error) Load() error {
 }
 
 // Store atomically stores the passed error.
-func (x *Error) Store(v error) {
-	x.v.Store(packError(v))
+func (x *Error) Store(val error) {
+	x.v.Store(packError(val))
 }

float64.go

@@ -37,10 +37,10 @@ type Float64 struct {
 var _zeroFloat64 float64
 
 // NewFloat64 creates a new Float64.
-func NewFloat64(v float64) *Float64 {
+func NewFloat64(val float64) *Float64 {
 	x := &Float64{}
-	if v != _zeroFloat64 {
-		x.Store(v)
+	if val != _zeroFloat64 {
+		x.Store(val)
 	}
 	return x
 }
@@ -51,14 +51,14 @@ func (x *Float64) Load() float64 {
 }
 
 // Store atomically stores the passed float64.
-func (x *Float64) Store(v float64) {
-	x.v.Store(math.Float64bits(v))
+func (x *Float64) Store(val float64) {
+	x.v.Store(math.Float64bits(val))
 }
 
 // Swap atomically stores the given float64 and returns the old
 // value.
-func (x *Float64) Swap(o float64) float64 {
-	return math.Float64frombits(x.v.Swap(math.Float64bits(o)))
+func (x *Float64) Swap(val float64) (old float64) {
+	return math.Float64frombits(x.v.Swap(math.Float64bits(val)))
 }
 
 // MarshalJSON encodes the wrapped float64 into JSON.

float64_ext.go

@@ -28,19 +28,19 @@ import (
 //go:generate bin/gen-atomicwrapper -name=Float64 -type=float64 -wrapped=Uint64 -pack=math.Float64bits -unpack=math.Float64frombits -swap -json -imports math -file=float64.go
 
 // Add atomically adds to the wrapped float64 and returns the new value.
-func (f *Float64) Add(s float64) float64 {
+func (f *Float64) Add(delta float64) float64 {
 	for {
 		old := f.Load()
-		new := old + s
+		new := old + delta
 		if f.CAS(old, new) {
 			return new
 		}
 	}
 }
 
 // Sub atomically subtracts from the wrapped float64 and returns the new value.
-func (f *Float64) Sub(s float64) float64 {
-	return f.Add(-s)
+func (f *Float64) Sub(delta float64) float64 {
+	return f.Add(-delta)
 }
 
 // CAS is an atomic compare-and-swap for float64 values.
@@ -58,8 +58,8 @@ func (f *Float64) Sub(s float64) float64 {
 //   }
 //
 // If CAS did not match NaN to match, then the above would loop forever.
-func (x *Float64) CAS(o, n float64) bool {
-	return x.v.CAS(math.Float64bits(o), math.Float64bits(n))
+func (x *Float64) CAS(old, new float64) (swapped bool) {
+	return x.v.CAS(math.Float64bits(old), math.Float64bits(new))
 }
 
 // String encodes the wrapped value as a string.

int32.go

@@ -36,8 +36,8 @@ type Int32 struct {
 }
 
 // NewInt32 creates a new Int32.
-func NewInt32(i int32) *Int32 {
-	return &Int32{v: i}
+func NewInt32(val int32) *Int32 {
+	return &Int32{v: val}
 }
 
 // Load atomically loads the wrapped value.
@@ -46,13 +46,13 @@ func (i *Int32) Load() int32 {
 }
 
 // Add atomically adds to the wrapped int32 and returns the new value.
-func (i *Int32) Add(n int32) int32 {
-	return atomic.AddInt32(&i.v, n)
+func (i *Int32) Add(delta int32) int32 {
+	return atomic.AddInt32(&i.v, delta)
 }
 
 // Sub atomically subtracts from the wrapped int32 and returns the new value.
-func (i *Int32) Sub(n int32) int32 {
-	return atomic.AddInt32(&i.v, -n)
+func (i *Int32) Sub(delta int32) int32 {
+	return atomic.AddInt32(&i.v, -delta)
 }
 
 // Inc atomically increments the wrapped int32 and returns the new value.
@@ -66,18 +66,18 @@ func (i *Int32) Dec() int32 {
 }
 
 // CAS is an atomic compare-and-swap.
-func (i *Int32) CAS(old, new int32) bool {
+func (i *Int32) CAS(old, new int32) (swapped bool) {
 	return atomic.CompareAndSwapInt32(&i.v, old, new)
 }
 
 // Store atomically stores the passed value.
-func (i *Int32) Store(n int32) {
-	atomic.StoreInt32(&i.v, n)
+func (i *Int32) Store(val int32) {
+	atomic.StoreInt32(&i.v, val)
 }
 
 // Swap atomically swaps the wrapped int32 and returns the old value.
-func (i *Int32) Swap(n int32) int32 {
-	return atomic.SwapInt32(&i.v, n)
+func (i *Int32) Swap(val int32) (old int32) {
+	return atomic.SwapInt32(&i.v, val)
 }
 
 // MarshalJSON encodes the wrapped int32 into JSON.

int64.go

@@ -36,8 +36,8 @@ type Int64 struct {
 }
 
 // NewInt64 creates a new Int64.
-func NewInt64(i int64) *Int64 {
-	return &Int64{v: i}
+func NewInt64(val int64) *Int64 {
+	return &Int64{v: val}
 }
 
 // Load atomically loads the wrapped value.
@@ -46,13 +46,13 @@ func (i *Int64) Load() int64 {
 }
 
 // Add atomically adds to the wrapped int64 and returns the new value.
-func (i *Int64) Add(n int64) int64 {
-	return atomic.AddInt64(&i.v, n)
+func (i *Int64) Add(delta int64) int64 {
+	return atomic.AddInt64(&i.v, delta)
 }
 
 // Sub atomically subtracts from the wrapped int64 and returns the new value.
-func (i *Int64) Sub(n int64) int64 {
-	return atomic.AddInt64(&i.v, -n)
+func (i *Int64) Sub(delta int64) int64 {
+	return atomic.AddInt64(&i.v, -delta)
 }
 
 // Inc atomically increments the wrapped int64 and returns the new value.
@@ -66,18 +66,18 @@ func (i *Int64) Dec() int64 {
 }
 
 // CAS is an atomic compare-and-swap.
-func (i *Int64) CAS(old, new int64) bool {
+func (i *Int64) CAS(old, new int64) (swapped bool) {
 	return atomic.CompareAndSwapInt64(&i.v, old, new)
 }
 
 // Store atomically stores the passed value.
-func (i *Int64) Store(n int64) {
-	atomic.StoreInt64(&i.v, n)
+func (i *Int64) Store(val int64) {
+	atomic.StoreInt64(&i.v, val)
 }
 
 // Swap atomically swaps the wrapped int64 and returns the old value.
-func (i *Int64) Swap(n int64) int64 {
-	return atomic.SwapInt64(&i.v, n)
+func (i *Int64) Swap(val int64) (old int64) {
+	return atomic.SwapInt64(&i.v, val)
 }
 
 // MarshalJSON encodes the wrapped int64 into JSON.

internal/gen-atomicint/main.go

@@ -144,8 +144,8 @@ type {{ .Name }} struct {
 }
 
 // New{{ .Name }} creates a new {{ .Name }}.
-func New{{ .Name }}(i {{ .Wrapped }}) *{{ .Name }} {
-	return &{{ .Name }}{v: i}
+func New{{ .Name }}(val {{ .Wrapped }}) *{{ .Name }} {
+	return &{{ .Name }}{v: val}
 }
 
 // Load atomically loads the wrapped value.
@@ -154,17 +154,17 @@ func (i *{{ .Name }}) Load() {{ .Wrapped }} {
 }
 
 // Add atomically adds to the wrapped {{ .Wrapped }} and returns the new value.
-func (i *{{ .Name }}) Add(n {{ .Wrapped }}) {{ .Wrapped }} {
-	return atomic.Add{{ .Name }}(&i.v, n)
+func (i *{{ .Name }}) Add(delta {{ .Wrapped }}) {{ .Wrapped }} {
+	return atomic.Add{{ .Name }}(&i.v, delta)
 }
 
 // Sub atomically subtracts from the wrapped {{ .Wrapped }} and returns the new value.
-func (i *{{ .Name }}) Sub(n {{ .Wrapped }}) {{ .Wrapped }} {
+func (i *{{ .Name }}) Sub(delta {{ .Wrapped }}) {{ .Wrapped }} {
 	return atomic.Add{{ .Name }}(&i.v,
 		{{- if .Unsigned -}}
-			^(n - 1)
+			^(delta - 1)
 		{{- else -}}
-			-n
+			-delta
 		{{- end -}}
 	)
 }
@@ -180,18 +180,18 @@ func (i *{{ .Name }}) Dec() {{ .Wrapped }} {
 }
 
 // CAS is an atomic compare-and-swap.
-func (i *{{ .Name }}) CAS(old, new {{ .Wrapped }}) bool {
+func (i *{{ .Name }}) CAS(old, new {{ .Wrapped }}) (swapped bool) {
 	return atomic.CompareAndSwap{{ .Name }}(&i.v, old, new)
 }
 
 // Store atomically stores the passed value.
-func (i *{{ .Name }}) Store(n {{ .Wrapped }}) {
-	atomic.Store{{ .Name }}(&i.v, n)
+func (i *{{ .Name }}) Store(val {{ .Wrapped }}) {
+	atomic.Store{{ .Name }}(&i.v, val)
 }
 
 // Swap atomically swaps the wrapped {{ .Wrapped }} and returns the old value.
-func (i *{{ .Name }}) Swap(n {{ .Wrapped }}) {{ .Wrapped }} {
-	return atomic.Swap{{ .Name }}(&i.v, n)
+func (i *{{ .Name }}) Swap(val {{ .Wrapped }}) (old {{ .Wrapped }}) {
+	return atomic.Swap{{ .Name }}(&i.v, val)
 }
 
 // MarshalJSON encodes the wrapped {{ .Wrapped }} into JSON.