Clarify Append* return values

args.go

@@ -84,8 +84,7 @@ func (a *Args) QueryString() []byte {
 	return a.buf
 }
 
-// AppendBytes appends query string to dst and returns dst
-// (which may be newly allocated).
+// AppendBytes appends query string to dst and returns the extended dst.
 func (a *Args) AppendBytes(dst []byte) []byte {
 	for i, n := 0, len(a.args); i < n; i++ {
 		kv := &a.args[i]

bytesconv.go

@@ -21,7 +21,7 @@ var gmtLocation = func() *time.Location {
 }()
 
 // AppendIPv4 appends string representation of the given ip v4 to dst
-// and returns the result (which may be newly allocated).
+// and returns the extended dst.
 func AppendIPv4(dst []byte, ip net.IP) []byte {
 	ip = ip.To4()
 	if ip == nil {
@@ -36,8 +36,7 @@ func AppendIPv4(dst []byte, ip net.IP) []byte {
 	return dst
 }
 
-// ParseIPv4 parses ip address from ipStr into dst and returns dst
-// (which may be newly allocated).
+// ParseIPv4 parses ip address from ipStr into dst and returns the extended dst.
 func ParseIPv4(dst net.IP, ipStr []byte) (net.IP, error) {
 	if len(dst) < net.IPv4len {
 		dst = make([]byte, net.IPv4len)
@@ -77,7 +76,7 @@ func ParseIPv4(dst net.IP, ipStr []byte) (net.IP, error) {
 }
 
 // AppendHTTPDate appends HTTP-compliant (RFC1123) representation of date
-// to dst and returns dst (which may be newly allocated).
+// to dst and returns the extended dst.
 func AppendHTTPDate(dst []byte, date time.Time) []byte {
 	return date.In(gmtLocation).AppendFormat(dst, time.RFC1123)
 }
@@ -87,7 +86,7 @@ func ParseHTTPDate(date []byte) (time.Time, error) {
 	return time.Parse(time.RFC1123, unsafeBytesToStr(date))
 }
 
-// AppendUint appends n to dst and returns dst (which may be newly allocated).
+// AppendUint appends n to dst and returns the extended dst.
 func AppendUint(dst []byte, n int) []byte {
 	if n < 0 {
 		panic("BUG: int must be positive")
@@ -329,8 +328,7 @@ func EqualBytesStr(b []byte, s string) bool {
 	return string(b) == s
 }
 
-// AppendBytesStr appends src to dst and returns dst
-// (which may be newly allocated).
+// AppendBytesStr appends src to dst and returns the extended dst.
 //
 // This function has no performance benefits comparing to append(dst, src...).
 // It is left here for backwards compatibility only.

cookie.go

@@ -142,8 +142,8 @@ func (c *Cookie) Reset() {
 	c.path = c.path[:0]
 }
 
-// AppendBytes appends cookie representation to dst and returns dst
-// (maybe newly allocated).
+// AppendBytes appends cookie representation to dst and returns
+// the extended dst.
 func (c *Cookie) AppendBytes(dst []byte) []byte {
 	if len(c.key) > 0 {
 		dst = appendQuotedArg(dst, c.key)

header.go

@@ -967,8 +967,8 @@ func (h *ResponseHeader) String() string {
 	return string(h.Header())
 }
 
-// AppendBytes appends response header representation to dst and returns dst
-// (which may be newly allocated).
+// AppendBytes appends response header representation to dst and returns
+// the extended dst.
 func (h *ResponseHeader) AppendBytes(dst []byte) []byte {
 	statusCode := h.StatusCode()
 	if statusCode < 0 {
@@ -1039,8 +1039,8 @@ func (h *RequestHeader) String() string {
 	return string(h.Header())
 }
 
-// AppendBytes appends request header representation to dst and returns dst
-// (which may be newly allocated).
+// AppendBytes appends request header representation to dst and returns
+// the extended dst.
 func (h *RequestHeader) AppendBytes(dst []byte) []byte {
 	// there is no need in h.parseRawHeaders() here - raw headers are specially handled below.
 	dst = append(dst, h.Method()...)

uri.go

@@ -378,8 +378,7 @@ func (x *URI) FullURI() []byte {
 	return x.fullURI
 }
 
-// AppendBytes appends full uri to dst and returns dst
-// (which may be newly allocated).
+// AppendBytes appends full uri to dst and returns the extended dst.
 func (x *URI) AppendBytes(dst []byte) []byte {
 	dst = x.appendSchemeHost(dst)
 	return append(dst, x.RequestURI()...)