From 2c8e9a79313f91a55e5c99fd20f88acc4035bd2d Mon Sep 17 00:00:00 2001
From: Ahsanul Haque <ahsanul@gmail.com>
Date: Fri, 12 Dec 2014 02:57:25 +0600
Subject: [PATCH] Commenting helpers package

---
 helpers/content.go |  8 ++++++++
 helpers/general.go |  3 +++
 helpers/path.go    |  9 +++++++--
 helpers/url.go     | 19 +++++++++++--------
 4 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/helpers/content.go b/helpers/content.go
index 9b46bbe83..1b0aea326 100644
--- a/helpers/content.go
+++ b/helpers/content.go
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//Package helpers implements general utility functions that work with and on content.
 package helpers
 
 import (
@@ -26,9 +27,13 @@ import (
 	"strings"
 )
 
+// Length of the summary that Hugo extracts from a content.
 var SummaryLength = 70
+
+// Custom divider "<!--more-->" let's user define where summarization ends.
 var SummaryDivider = []byte("<!--more-->")
 
+//StripHTML accepts a string, strips out all HTML tags and returns it.
 func StripHTML(s string) string {
 	output := ""
 
@@ -61,10 +66,12 @@ func StripHTML(s string) string {
 	return output
 }
 
+// StripEmptyNav strips out empty <nav> tags from content.
 func StripEmptyNav(in []byte) []byte {
 	return bytes.Replace(in, []byte("<nav>\n</nav>\n\n"), []byte(``), -1)
 }
 
+//BytesToHTML converts bytes to type template.HTML.
 func BytesToHTML(b []byte) template.HTML {
 	return template.HTML(string(b))
 }
@@ -109,6 +116,7 @@ func MarkdownRenderWithTOC(content []byte, documentId string) []byte {
 		GetMarkdownExtensions())
 }
 
+//ExtractTOC extracts Table of Contents from content.
 func ExtractTOC(content []byte) (newcontent []byte, toc []byte) {
 	origContent := make([]byte, len(content))
 	copy(origContent, content)
diff --git a/helpers/general.go b/helpers/general.go
index cf3c0ac54..c1a6e034f 100644
--- a/helpers/general.go
+++ b/helpers/general.go
@@ -24,6 +24,7 @@ import (
 	"strings"
 )
 
+//Filepath separator defined by os.Separator.
 const FilePathSeparator = string(filepath.Separator)
 
 func FindAvailablePort() (*net.TCPAddr, error) {
@@ -39,6 +40,7 @@ func FindAvailablePort() (*net.TCPAddr, error) {
 	return nil, err
 }
 
+// InStringArray checks if a string is an element of a slice of strings and returns a boolean value.
 func InStringArray(arr []string, el string) bool {
 	for _, v := range arr {
 		if v == el {
@@ -48,6 +50,7 @@ func InStringArray(arr []string, el string) bool {
 	return false
 }
 
+// GuessType attempts to guess the type of file from a given string.
 func GuessType(in string) string {
 	switch strings.ToLower(in) {
 	case "md", "markdown", "mdown":
diff --git a/helpers/path.go b/helpers/path.go
index b65533d8a..ec6da75e2 100644
--- a/helpers/path.go
+++ b/helpers/path.go
@@ -70,7 +70,7 @@ func ReplaceExtension(path string, newExt string) string {
 	return f + "." + newExt
 }
 
-// Check if Exists && is Directory
+// DirExists checks if a path exists and is a directory.
 func DirExists(path string, fs afero.Fs) (bool, error) {
 	fi, err := fs.Stat(path)
 	if err == nil && fi.IsDir() {
@@ -82,6 +82,7 @@ func DirExists(path string, fs afero.Fs) (bool, error) {
 	return false, err
 }
 
+//IsDir check if a given path is a directory.
 func IsDir(path string, fs afero.Fs) (bool, error) {
 	fi, err := fs.Stat(path)
 	if err != nil {
@@ -90,6 +91,7 @@ func IsDir(path string, fs afero.Fs) (bool, error) {
 	return fi.IsDir(), nil
 }
 
+//IsEmpty checks if a given path is empty.
 func IsEmpty(path string, fs afero.Fs) (bool, error) {
 	if b, _ := Exists(path, fs); !b {
 		return false, fmt.Errorf("%q path does not exist", path)
@@ -114,7 +116,7 @@ func IsEmpty(path string, fs afero.Fs) (bool, error) {
 	}
 }
 
-// Check if File / Directory Exists
+// Check if a file or directory exists.
 func Exists(path string, fs afero.Fs) (bool, error) {
 	_, err := fs.Stat(path)
 	if err == nil {
@@ -151,6 +153,7 @@ func MakePathRelative(inPath string, possibleDirectories ...string) (string, err
 	return inPath, errors.New("Can't extract relative path, unknown prefix")
 }
 
+//Filename takes a path, strips out the extension and returns the name of the file.
 func Filename(in string) (name string) {
 	name, _ = FileAndExt(in)
 	return
@@ -197,6 +200,7 @@ func FileAndExtSep(in, ext, base, pathSeparator string) (name string) {
 
 }
 
+//GetRelativePath returns the relative path of a given path.
 func GetRelativePath(path, base string) (final string, err error) {
 	if filepath.IsAbs(path) && base == "" {
 		return "", errors.New("source: missing base directory")
@@ -275,6 +279,7 @@ func PrettifyPath(in string) string {
 	}
 }
 
+//FindCWD returns the current working directory from where the Hugo executable is run from.
 func FindCWD() (string, error) {
 	serverFile, err := filepath.Abs(os.Args[0])
 
diff --git a/helpers/url.go b/helpers/url.go
index a2dc0ac69..59769f852 100644
--- a/helpers/url.go
+++ b/helpers/url.go
@@ -21,6 +21,7 @@ import (
 	"strings"
 )
 
+//SanitizeUrl sanitizes the input URL string.
 func SanitizeUrl(in string) string {
 	url, err := purell.NormalizeURLString(in, purell.FlagsSafe|purell.FlagRemoveTrailingSlash|purell.FlagRemoveDotSegments|purell.FlagRemoveDuplicateSlashes|purell.FlagRemoveUnnecessaryHostDots|purell.FlagRemoveEmptyPortSeparator)
 	if err != nil {
@@ -46,7 +47,7 @@ func Urlize(uri string) string {
 	return x
 }
 
-// Combines a base with a path
+// Combines base URL with content path to create full URL paths.
 // Example
 //    base:   http://spf13.com/
 //    path:   post/how-i-blog
@@ -95,7 +96,7 @@ func UrlPrep(ugly bool, in string) string {
 	}
 }
 
-// Don't Return /index.html portion.
+// PrettifyUrl takes a URL string and returns a semantic, clean URL.
 func PrettifyUrl(in string) string {
 	x := PrettifyUrlPath(in)
 
@@ -110,9 +111,10 @@ func PrettifyUrl(in string) string {
 	return x
 }
 
-// /section/name.html -> /section/name/index.html
-// /section/name/  -> /section/name/index.html
-// /section/name/index.html -> /section/name/index.html
+//PrettifyUrlPath takes a URL path to a content and converts it to enable pretty URLS.
+//	/section/name.html becomes /section/name/index.html
+//	/section/name/  becomes /section/name/index.html
+//	/section/name/index.html becomes /section/name/index.html
 func PrettifyUrlPath(in string) string {
 	if path.Ext(in) == "" {
 		// /section/name/  -> /section/name/index.html
@@ -132,9 +134,10 @@ func PrettifyUrlPath(in string) string {
 	}
 }
 
-// /section/name/index.html -> /section/name.html
-// /section/name/  -> /section/name.html
-// /section/name.html -> /section/name.html
+//Uglify does the opposite of PrettifyPath().
+// 	/section/name/index.html becomes /section/name.html
+// 	/section/name/  becomes /section/name.html
+// 	/section/name.html becomes /section/name.html
 func Uglify(in string) string {
 	if path.Ext(in) == "" {
 		if len(in) < 2 {