Commenting helpers package

diff --git a/helpers/content.go b/helpers/content.go
index 9b46bbe83477ab1a901b8ff8be4630a06b68c89c..1b0aea326ae7b72f6f7e6844bf976b7fe75b7a7e 100644 (file)
--- 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 cf3c0ac542483248a9d6d2953e7790e53c041e42..c1a6e034f2bbfccb3a8b98d3a18689992908f0d7 100644 (file)
--- 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 b65533d8a80f70d4b87137d950eee97efba8ab39..ec6da75e2e7b1aeb14f2ebcb823eda71910b2c86 100644 (file)
--- 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 a2dc0ac69f960553e85d05f6a6376257d17be38c..59769f852b070a0310b2b4a1eea1416a0b5152a3 100644 (file)
--- 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 {