Wrap comments helpers package to fit 80-column width

Add an initial space after `//` where appropriate.
Minor copyediting.

helpers/content.go

@@ -11,8 +11,10 @@
 // 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. The helper functions defined here
+// Package helpers implements general utility functions that work with
-//lay down the foundation of how Hugo works with files, filepaths and does string operations on content.
+// and on content.  The helper functions defined here lay down the
+// foundation of how Hugo works with files and filepaths, and perform
+// string operations on content.
 package helpers
 
 import (
@@ -34,7 +36,7 @@ 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.
+// StripHTML accepts a string, strips out all HTML tags and returns it.
 func StripHTML(s string) string {
 	output := ""
 
@@ -72,7 +74,7 @@ func StripEmptyNav(in []byte) []byte {
 	return bytes.Replace(in, []byte("<nav>\n</nav>\n\n"), []byte(``), -1)
 }
 
-//BytesToHTML converts bytes to type template.HTML.
+// BytesToHTML converts bytes to type template.HTML.
 func BytesToHTML(b []byte) template.HTML {
 	return template.HTML(string(b))
 }
@@ -127,7 +129,7 @@ func MarkdownRenderWithTOC(ctx RenderingContext) []byte {
 		GetMarkdownExtensions())
 }
 
-//ExtractTOC extracts Table of Contents from content.
+// ExtractTOC extracts Table of Contents from content.
 func ExtractTOC(content []byte) (newcontent []byte, toc []byte) {
 	origContent := make([]byte, len(content))
 	copy(origContent, content)
@@ -197,7 +199,7 @@ func TotalWords(s string) int {
 	return len(strings.Fields(s))
 }
 
-//WordCount takes content and returns a map of words and count of each word.
+// WordCount takes content and returns a map of words and count of each word.
 func WordCount(s string) map[string]int {
 	m := make(map[string]int)
 	for _, f := range strings.Fields(s) {
@@ -207,12 +209,13 @@ func WordCount(s string) map[string]int {
 	return m
 }
 
-//RemoveSummaryDivider removes summary-divider <!--more--> from content.
+// RemoveSummaryDivider removes summary-divider <!--more--> from content.
 func RemoveSummaryDivider(content []byte) []byte {
 	return bytes.Replace(content, SummaryDivider, []byte(""), -1)
 }
 
-//TruncateWords takes content and na int and shortens down the number of words in the content down to the number of int.
+// TruncateWords takes content and an int and shortens down the number
+// of words in the content down to the number of int.
 func TruncateWords(s string, max int) string {
 	words := strings.Fields(s)
 	if max > len(words) {
@@ -222,7 +225,8 @@ func TruncateWords(s string, max int) string {
 	return strings.Join(words[:max], " ")
 }
 
-//TruncateWordsToWholeSentence takes content and an int and returns entire sentences from content, delimited by the int.
+// TruncateWordsToWholeSentence takes content and an int
+// and returns entire sentences from content, delimited by the int.
 func TruncateWordsToWholeSentence(s string, max int) string {
 	words := strings.Fields(s)
 	if max > len(words) {
@@ -241,6 +245,8 @@ func TruncateWordsToWholeSentence(s string, max int) string {
 	return strings.Join(words[:max], " ")
 }
 
+// GetRstContent calls the Python script rst2html as an external helper
+// to convert reStructuredText content to HTML.
 func GetRstContent(content []byte) string {
 	cleanContent := bytes.Replace(content, SummaryDivider, []byte(""), 1)
 

helpers/general.go

@@ -24,7 +24,7 @@ import (
 	"strings"
 )
 
-//Filepath separator defined by os.Separator.
+// Filepath separator defined by os.Separator.
 const FilePathSeparator = string(filepath.Separator)
 
 func FindAvailablePort() (*net.TCPAddr, error) {
@@ -40,7 +40,8 @@ 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.
+// 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 {
@@ -64,31 +65,32 @@ func GuessType(in string) string {
 	return "unknown"
 }
 
-//ReaderToBytes takes an io.Reader argument, reads from it and returns bytes.
+// ReaderToBytes takes an io.Reader argument, reads from it
+// and returns bytes.
 func ReaderToBytes(lines io.Reader) []byte {
 	b := new(bytes.Buffer)
 	b.ReadFrom(lines)
 	return b.Bytes()
 }
 
-//ReaderToString is the same as ReaderToBytes, but returns a string.
+// ReaderToString is the same as ReaderToBytes, but returns a string.
 func ReaderToString(lines io.Reader) string {
 	b := new(bytes.Buffer)
 	b.ReadFrom(lines)
 	return b.String()
 }
 
-//StringToReader does the opposite of ReaderToString.
+// StringToReader does the opposite of ReaderToString.
 func StringToReader(in string) io.Reader {
 	return strings.NewReader(in)
 }
 
-//BytesToReader does the opposite of ReaderToBytes.
+// BytesToReader does the opposite of ReaderToBytes.
 func BytesToReader(in []byte) io.Reader {
 	return bytes.NewReader(in)
 }
 
-// sliceToLower goes through the source slice and lowers all values.
+// SliceToLower goes through the source slice and lowers all values.
 func SliceToLower(s []string) []string {
 	if s == nil {
 		return nil
@@ -102,7 +104,7 @@ func SliceToLower(s []string) []string {
 	return l
 }
 
-//Md5String takes a string and returns a MD5 Hash of it.
+// Md5String takes a string and returns its MD5 hash.
 func Md5String(f string) string {
 	h := md5.New()
 	h.Write([]byte(f))

helpers/path.go

@@ -28,15 +28,16 @@ import (
 
 var sanitizeRegexp = regexp.MustCompile("[^a-zA-Z0-9./_-]")
 
-// Take a string with any characters and replace it so the string could be used in a path.
+// MakePath takes a string with any characters and replace it
-// MakePath creates a Unicode sanitized string, with the spaces replaced, whilst
+// so the string could be used in a path.
-// preserving the original casing of the string.
+// It does so by creating a Unicode-sanitized string, with the spaces replaced,
+// whilst preserving the original casing of the string.
 // E.g. Social Media -> Social-Media
 func MakePath(s string) string {
 	return UnicodeSanitize(strings.Replace(strings.TrimSpace(s), " ", "-", -1))
 }
 
-// MakePathToLower creates a Unicode santized string, with the spaces replaced,
+// MakePathToLower creates a Unicode-sanitized string, with the spaces replaced,
 // and transformed to lower case.
 // E.g. Social Media -> social-media
 func MakePathToLower(s string) string {
@@ -65,7 +66,8 @@ func UnicodeSanitize(s string) string {
 	return string(target)
 }
 
-//ReplaceExtension takes a path and an extension, strips the old extension and returns the path with the new extension.
+// ReplaceExtension takes a path and an extension, strips the old extension
+// and returns the path with the new extension.
 func ReplaceExtension(path string, newExt string) string {
 	f, _ := FileAndExt(path)
 	return f + "." + newExt
@@ -83,7 +85,7 @@ func DirExists(path string, fs afero.Fs) (bool, error) {
 	return false, err
 }
 
-//IsDir check if a given path is a directory.
+// IsDir checks if a given path is a directory.
 func IsDir(path string, fs afero.Fs) (bool, error) {
 	fi, err := fs.Stat(path)
 	if err != nil {
@@ -92,7 +94,7 @@ func IsDir(path string, fs afero.Fs) (bool, error) {
 	return fi.IsDir(), nil
 }
 
-//IsEmpty checks if a given path is empty.
+// 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)
@@ -154,7 +156,8 @@ 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.
+// 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
@@ -162,14 +165,18 @@ func Filename(in string) (name string) {
 
 // FileAndExt returns the filename and any extension of a file path as
 // two separate strings.
-// If path, in, contains a directory name ending in a slash then
+//
-// both name and ext will be empty strings.
+// If the path, in, contains a directory name ending in a slash,
+// then both name and ext will be empty strings.
+//
 // If the path, in, is either the current directory, the parent
-// directory or the root directory, or an empty string, then both
+// directory or the root directory, or an empty string,
-// name and ext will be empty strings.
+// then both name and ext will be empty strings.
-// If the path, in, represents the path of a file without an extension
+//
+// If the path, in, represents the path of a file without an extension,
 // then name will be the name of the file and ext will be an empty string.
-// If the path, in, represents a filename with an extension then
+//
+// If the path, in, represents a filename with an extension,
 // then name will be the filename minus any extension - including the dot
 // and ext will contain the extension - minus the dot.
 func FileAndExt(in string) (name string, ext string) {
@@ -201,7 +208,7 @@ func FileAndExtSep(in, ext, base, pathSeparator string) (name string) {
 
 }
 
-//GetRelativePath returns the relative path of a given path.
+// 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")
@@ -216,8 +223,9 @@ func GetRelativePath(path, base string) (final string, err error) {
 	return name, nil
 }
 
-// Given a source path, determine the section
+// Given a source path, determine the section.
-// A section is the part between the root slash and the second slash or before the first slash
+// A section is the part between the root slash and the second slash
+// or before the first slash.
 func GuessSection(in string) string {
 	parts := strings.Split(in, FilePathSeparator)
 	// This will include an empty entry before and after paths with leading and trailing slashes
@@ -258,10 +266,10 @@ func PathPrep(ugly bool, in string) string {
 	}
 }
 
-// Same as PrettifyUrlPath() but for paths.
+// Same as PrettifyUrlPath() but for file paths.
-// 	/section/name.html becomes /section/name/index.html
+//     /section/name.html       becomes /section/name/index.html
-// 	/section/name/  becomes /section/name/index.html
+//     /section/name/           becomes /section/name/index.html
-// 	/section/name/index.html becomes /section/name/index.html
+//     /section/name/index.html becomes /section/name/index.html
 func PrettifyPath(in string) string {
 	if filepath.Ext(in) == "" {
 		// /section/name/  -> /section/name/index.html
@@ -281,7 +289,8 @@ func PrettifyPath(in string) string {
 	}
 }
 
-//FindCWD returns the current working directory from where the Hugo executable is run.
+// FindCWD returns the current working directory from where the Hugo
+// executable is run.
 func FindCWD() (string, error) {
 	serverFile, err := filepath.Abs(os.Args[0])
 
@@ -305,7 +314,7 @@ func FindCWD() (string, error) {
 	return path, nil
 }
 
-//Same as WriteToDisk but checks to see if file/directory already exists.
+// Same as WriteToDisk but checks to see if file/directory already exists.
 func SafeWriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error) {
 	dir, _ := filepath.Split(inpath)
 	ospath := filepath.FromSlash(dir)

helpers/pygments.go

@@ -25,7 +25,8 @@ import (
 
 const pygmentsBin = "pygmentize"
 
-//HasPygments checks to see if Pygments is installed and available on the system.
+// HasPygments checks to see if Pygments is installed and available
+// on the system.
 func HasPygments() bool {
 	if _, err := exec.LookPath(pygmentsBin); err != nil {
 		return false
@@ -33,7 +34,7 @@ func HasPygments() bool {
 	return true
 }
 
-//Highlight takes some code and returns highlighted code.
+// Highlight takes some code and returns highlighted code.
 func Highlight(code string, lexer string) string {
 
 	if !HasPygments() {

helpers/url.go

@@ -21,7 +21,7 @@ import (
 	"strings"
 )
 
-//SanitizeUrl sanitizes the input URL string.
+// 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 {
@@ -111,10 +111,11 @@ func PrettifyUrl(in string) string {
 	return x
 }
 
-//PrettifyUrlPath takes a URL path to a content and converts it to enable pretty URLS.
+// PrettifyUrlPath takes a URL path to a content and converts it
-//	/section/name.html becomes /section/name/index.html
+// to enable pretty URLs.
-//	/section/name/  becomes /section/name/index.html
+//     /section/name.html       becomes /section/name/index.html
-//	/section/name/index.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
@@ -134,10 +135,10 @@ func PrettifyUrlPath(in string) string {
 	}
 }
 
-//Uglify does the opposite of PrettifyPath().
+// Uglify does the opposite of PrettifyUrlPath().
-// 	/section/name/index.html becomes /section/name.html
+//     /section/name/index.html becomes /section/name.html
-// 	/section/name/  becomes /section/name.html
+//     /section/name/           becomes /section/name.html
-// 	/section/name.html becomes /section/name.html
+//     /section/name.html       becomes /section/name.html
 func Uglify(in string) string {
 	if path.Ext(in) == "" {
 		if len(in) < 2 {
@@ -162,7 +163,7 @@ func Uglify(in string) string {
 	}
 }
 
-// Same as FileAndExt, but for Urls
+// Same as FileAndExt, but for URLs.
 func ResourceAndExt(in string) (name string, ext string) {
 	ext = path.Ext(in)
 	base := path.Base(in)