From 64e6a7654f134c18e1a21efa9ccd20c477c84f87 Mon Sep 17 00:00:00 2001
From: Bo-Yi Wu <appleboy.tw@gmail.com>
Date: Tue, 28 Jan 2020 11:38:45 +0800
Subject: [PATCH] docs(path): improve comments (#2223)

* chore(path): improve comments

copy from https://github.com/julienschmidt/httprouter/commit/15782a78c61201cf2fdbc138d63aa60fff114695

* fix typo

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>
---
 path.go | 24 +++++++++++++++++-------
 tree.go |  2 +-
 2 files changed, 18 insertions(+), 8 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 {
diff --git a/tree.go b/tree.go
index 89f74deb..2f6b1890 100644
--- a/tree.go
+++ b/tree.go
@@ -401,7 +401,7 @@ func (n *node) insertChild(numParams uint8, path string, fullPath string, handle
 		return
 	}
 
-	// If no wildcard was found, simple insert the path and handle
+	// If no wildcard was found, simply insert the path and handle
 	n.path = path
 	n.handlers = handlers
 	n.fullPath = fullPath