helpers: Fix and add Godoc in path*

2 files changed, 36 insertions, 16 deletions

diff --git a/helpers/path.go b/helpers/path.go
index 69f10880e..34b7675fc 100644
--- a/helpers/path.go
+++ b/helpers/path.go
@@ -85,10 +85,16 @@ func MakePathSanitized(s string) string {
 	return strings.ToLower(MakePath(s))
 }
 
+// MakeTitle converts the path given to a suitable title, trimming whitespace
+// and replacing hyphens with whitespace.
 func MakeTitle(inpath string) string {
 	return strings.Replace(strings.TrimSpace(inpath), "-", " ", -1)
 }
 
+// UnicodeSanitize sanitizes string to be used in Hugo URL's, allowing only
+// a predefined set of special Unicode characters.
+// If RemovePathAccents configuration flag is enabled, Uniccode accents
+// are also removed.
 func UnicodeSanitize(s string) string {
 	source := []rune(s)
 	target := make([]rune, 0, len(source))
@@ -123,6 +129,8 @@ func ReplaceExtension(path string, newExt string) string {
 	return f + "." + newExt
 }
 
+// AbsPathify creates an absolute path if given a relative path. If already
+// absolute, the path is just cleaned.
 func AbsPathify(inPath string) string {
 	if filepath.IsAbs(inPath) {
 		return filepath.Clean(inPath)
@@ -132,11 +140,13 @@ func AbsPathify(inPath string) string {
 	return filepath.Clean(filepath.Join(viper.GetString("WorkingDir"), inPath))
 }
 
+// GetStaticDirPath returns the absolute path to the static file dir
+// for the current Hugo project.
 func GetStaticDirPath() string {
 	return AbsPathify(viper.GetString("StaticDir"))
 }
 
-// Get the root directory of the current theme, if there is one.
+// GetThemeDir gets the root directory of the current theme, if there is one.
 // If there is no theme, returns the empty string.
 func GetThemeDir() string {
 	if ThemeSet() {
@@ -151,7 +161,7 @@ func GetThemeStaticDirPath() (string, error) {
 	return getThemeDirPath("static")
 }
 
-// GetThemeStaticDirPath returns the theme's data dir path if theme is set.
+// GetThemeDataDirPath returns the theme's data dir path if theme is set.
 // If theme is set and the data dir doesn't exist, an error is returned.
 func GetThemeDataDirPath() (string, error) {
 	return getThemeDirPath("data")
@@ -168,21 +178,25 @@ func getThemeDirPath(path string) (string, error) {
 	return themeDir, nil
 }
 
-// Get the 'static' directory of the current theme, if there is one.
-// Ignores underlying errors. Candidate for deprecation?
+// GetThemesDirPath gets the static files directory of the current theme, if there is one.
+// Ignores underlying errors.
+// TODO(bep) Candidate for deprecation?
 func GetThemesDirPath() string {
 	dir, _ := getThemeDirPath("static")
 	return dir
 }
 
+// MakeStaticPathRelative makes a relative path to the static files directory.
+// It does so by taking either the project's static path or the theme's static
+// path into consideration.
 func MakeStaticPathRelative(inPath string) (string, error) {
 	staticDir := GetStaticDirPath()
 	themeStaticDir := GetThemesDirPath()
 
-	return MakePathRelative(inPath, staticDir, themeStaticDir)
+	return makePathRelative(inPath, staticDir, themeStaticDir)
 }
 
-func MakePathRelative(inPath string, possibleDirectories ...string) (string, error) {
+func makePathRelative(inPath string, possibleDirectories ...string) (string, error) {
 
 	for _, currentPath := range possibleDirectories {
 		if strings.HasPrefix(inPath, currentPath) {
@@ -195,7 +209,8 @@ func MakePathRelative(inPath string, possibleDirectories ...string) (string, err
 // Should be good enough for Hugo.
 var isFileRe = regexp.MustCompile(".*\\..{1,6}$")
 
-// Expects a relative path starting after the content directory.
+// GetDottedRelativePath expects a relative path starting after the content directory.
+// It returns a relative path with dots ("..") navigating up the path structure.
 func GetDottedRelativePath(inPath string) string {
 	inPath = filepath.Clean(filepath.FromSlash(inPath))
 
@@ -299,6 +314,7 @@ func GetRelativePath(path, base string) (final string, err error) {
 	return name, nil
 }
 
+// PaginateAliasPath creates a path used to access the aliases in the paginator.
 func PaginateAliasPath(base string, page int) string {
 	paginatePath := viper.GetString("paginatePath")
 	uglify := viper.GetBool("UglyURLs")
@@ -349,6 +365,8 @@ func GuessSection(in string) string {
 	return parts[0]
 }
 
+// PathPrep prepares the path using the uglify setting to create paths on
+// either the form /section/name/index.html or /section/name.html.
 func PathPrep(ugly bool, in string) string {
 	if ugly {
 		return Uglify(in)
@@ -356,7 +374,7 @@ func PathPrep(ugly bool, in string) string {
 	return PrettifyPath(in)
 }
 
-// Same as PrettifyURLPath() but for file paths.
+// PrettifyPath is the same as PrettifyURLPath but for file paths.
 //     /section/name.html       becomes /section/name/index.html
 //     /section/name/           becomes /section/name/index.html
 //     /section/name/index.html becomes /section/name/index.html
@@ -381,7 +399,7 @@ func prettifyPath(in string, b filepathPathBridge) string {
 	return b.Join(b.Dir(in), name, "index"+ext)
 }
 
-// Extract the root paths from the supplied list of paths.
+// ExtractRootPaths extracts the root paths from the supplied list of paths.
 // The resulting root path will not contain any file separators, but there
 // may be duplicates.
 // So "/content/section/" becomes "content"
@@ -445,16 +463,18 @@ func SymbolicWalk(fs afero.Fs, root string, walker filepath.WalkFunc) error {
 
 }
 
-// Same as WriteToDisk but checks to see if file/directory already exists.
+// SafeWriteToDisk is the same as WriteToDisk
+// but it also checks to see if file/directory already exists.
 func SafeWriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error) {
 	return afero.SafeWriteReader(fs, inpath, r)
 }
 
-// Writes content to disk.
+// WriteToDisk writes content to disk.
 func WriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error) {
 	return afero.WriteReader(fs, inpath, r)
 }
 
+// GetTempDir returns a temporary directory with the given sub path.
 func GetTempDir(subPath string, fs afero.Fs) string {
 	return afero.GetTempDir(fs, subPath)
 }
@@ -474,17 +494,17 @@ func IsEmpty(path string, fs afero.Fs) (bool, error) {
 	return afero.IsEmpty(fs, path)
 }
 
-// Check if a file contains a specified string.
+// FileContains checks if a file contains a specified string.
 func FileContains(filename string, subslice []byte, fs afero.Fs) (bool, error) {
 	return afero.FileContainsBytes(fs, filename, subslice)
 }
 
-// Check if a file contains any of the specified strings.
+// FileContainsAny checks if a file contains any of the specified strings.
 func FileContainsAny(filename string, subslices [][]byte, fs afero.Fs) (bool, error) {
 	return afero.FileContainsAnyBytes(fs, filename, subslices)
 }
 
-// Check if a file or directory exists.
+// Exists checks if a file or directory exists.
 func Exists(path string, fs afero.Fs) (bool, error) {
 	return afero.Exists(fs, path)
 }
diff --git a/helpers/path_test.go b/helpers/path_test.go
index 1806cc2e0..a1769f1da 100644
--- a/helpers/path_test.go
+++ b/helpers/path_test.go
@@ -152,12 +152,12 @@ func TestMakePathRelative(t *testing.T) {
 	}
 
 	for i, d := range data {
-		output, _ := MakePathRelative(d.inPath, d.path1, d.path2)
+		output, _ := makePathRelative(d.inPath, d.path1, d.path2)
 		if d.output != output {
 			t.Errorf("Test #%d failed. Expected %q got %q", i, d.output, output)
 		}
 	}
-	_, error := MakePathRelative("a/b/c.ss", "/a/c", "/d/c", "/e/f")
+	_, error := makePathRelative("a/b/c.ss", "/a/c", "/d/c", "/e/f")
 
 	if error == nil {
 		t.Errorf("Test failed, expected error")