Add descriptive comments to most Go functions

1 files changed, 15 insertions, 0 deletions

diff --git a/url.go b/url.go
index f415c2d..b9c5753 100644
--- a/url.go
+++ b/url.go
@@ -15,6 +15,8 @@ var (
 	errNoRefSpec  = errors.New("no ref spec")
 )
 
+// getParamRefTypeName looks at the query parameters in an HTTP request and
+// returns its ref name and type, if any.
 func getParamRefTypeName(request *http.Request) (retRefType, retRefName string, err error) {
 	rawQuery := request.URL.RawQuery
 	queryValues, err := url.ParseQuery(rawQuery)
@@ -44,6 +46,8 @@ func getParamRefTypeName(request *http.Request) (retRefType, retRefName string,
 	return
 }
 
+// parseReqURI parses an HTTP request URL, and returns a slice of path segments
+// and the query parameters. It handles %2F correctly.
 func parseReqURI(requestURI string) (segments []string, params url.Values, err error) {
 	path, paramsStr, _ := strings.Cut(requestURI, "?")
 
@@ -60,6 +64,9 @@ func parseReqURI(requestURI string) (segments []string, params url.Values, err e
 	return
 }
 
+// redirectDir returns true and redirects the user to a version of the URL with
+// a trailing slash, if and only if the request URL does not already have a
+// trailing slash.
 func redirectDir(writer http.ResponseWriter, request *http.Request) bool {
 	requestURI := request.RequestURI
 
@@ -79,6 +86,9 @@ func redirectDir(writer http.ResponseWriter, request *http.Request) bool {
 	return false
 }
 
+// redirectNoDir returns true and redirects the user to a version of the URL
+// without a trailing slash, if and only if the request URL has a trailing
+// slash.
 func redirectNoDir(writer http.ResponseWriter, request *http.Request) bool {
 	requestURI := request.RequestURI
 
@@ -98,6 +108,8 @@ func redirectNoDir(writer http.ResponseWriter, request *http.Request) bool {
 	return false
 }
 
+// redirectUnconditionally unconditionally redirects the user back to the
+// current page while preserving query parameters.
 func redirectUnconditionally(writer http.ResponseWriter, request *http.Request) {
 	requestURI := request.RequestURI
 
@@ -113,6 +125,8 @@ func redirectUnconditionally(writer http.ResponseWriter, request *http.Request)
 	http.Redirect(writer, request, path+rest, http.StatusSeeOther)
 }
 
+// segmentsToURL joins URL segments to the path component of a URL.
+// Each segment is escaped properly first.
 func segmentsToURL(segments []string) string {
 	for i, segment := range segments {
 		segments[i] = url.PathEscape(segment)
@@ -120,6 +134,7 @@ func segmentsToURL(segments []string) string {
 	return strings.Join(segments, "/")
 }
 
+// anyContain returns true if and only if ss contains a string that contains c.
 func anyContain(ss []string, c string) bool {
 	for _, s := range ss {
 		if strings.Contains(s, c) {