From 35e036da081c1839d403e7e672c82e7e80bb4857 Mon Sep 17 00:00:00 2001
From: Bo-Yi Wu <appleboy.tw@gmail.com>
Date: Mon, 27 Jan 2020 17:20:23 +0800
Subject: [PATCH] chore(path): improve comments

copy from https://github.com/julienschmidt/httprouter/commit/15782a78c61201cf2fdbc138d63aa60fff114695
---
 path.go | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/path.go b/path.go
index 37247d41..51346e4a 100644
--- a/path.go
+++ b/path.go
@@ -53,8 +53,9 @@ func cleanPath(p string) string {
 	trailing := n > 1 && p[n-1] == '/'
 
 	// A bit more clunky without a 'lazybuf' like the path package, but the loop
-	// gets completely inlined (bufApp). So in contrast to the path package this
-	// loop has no expensive function calls (except 1x make)
+	// gets completely inlined (bufApp calls).
+	// loop has no expensive function calls (except 1x make)		// So in contrast to the path package this loop has no expensive function
+	// calls (except make, if needed).
 
 	for r < n {
 		switch {
@@ -90,14 +91,14 @@ func cleanPath(p string) string {
 			}
 
 		default:
-			// real path element.
-			// add slash if needed
+			// Real path element.
+			// Add slash if needed
 			if w > 1 {
 				bufApp(&buf, p, w, '/')
 				w++
 			}
 
-			// copy element
+			// Copy element
 			for r < n && p[r] != '/' {
 				bufApp(&buf, p, w, p[r])
 				w++
@@ -106,26 +107,35 @@ func cleanPath(p string) string {
 		}
 	}
 
-	// re-append trailing slash
+	// Re-append trailing slash
 	if trailing && w > 1 {
 		bufApp(&buf, p, w, '/')
 		w++
 	}
 
+	// If the original string was not modified (or only shortened at the end),
+	// return the respective substring of the original string.
+	// Otherwise return a new string from the buffer.
 	if len(buf) == 0 {
 		return p[:w]
 	}
 	return string(buf[:w])
 }
 
-// internal helper to lazily create a buffer if necessary.
+// Internal helper to lazily create a buffer if necessary.
+// Calls to this function get inlined.
 func bufApp(buf *[]byte, s string, w int, c byte) {
 	b := *buf
 	if len(b) == 0 {
+		// No modification of the original string so far.
+		// If the next character is the same as in the original string, we do
+		// not yet have to allocate a buffer.
 		if s[w] == c {
 			return
 		}
 
+		// Otherwise use either the stack buffer, if it is large enough, or
+		// allocate a new buffer on the heap, and copy all previous characters.
 		if l := len(s); l > cap(b) {
 			*buf = make([]byte, len(s))
 		} else {