Add some missing doc comments

As pointed out by the linter, some exported functions and types are
missing doc comments.
The linter warnings have been reduced from 194 to 116.
Not all missing comments have been added in this commit though.

helpers/baseURL.go

@@ -30,7 +30,8 @@ func (b BaseURL) String() string {
 	return b.urlStr
 }
 
-// Protocol is normally on the form "scheme://", i.e. "webcal://".
+// WithProtocol returns the BaseURL prefixed with the given protocol.
+// The Protocol is normally of the form "scheme://", i.e. "webcal://".
 func (b BaseURL) WithProtocol(protocol string) (string, error) {
 	u := b.URL()
 
@@ -55,8 +56,9 @@ func (b BaseURL) WithProtocol(protocol string) (string, error) {
 	return u.String(), nil
 }
 
+// URL returns a copy of the internal URL.
+// The copy can be safely used and modified.
 func (b BaseURL) URL() *url.URL {
-	// create a copy as it will be modified.
 	c := *b.url
 	return &c
 }

helpers/content.go

@@ -42,6 +42,7 @@ var SummaryLength = 70
 // SummaryDivider denotes where content summarization should end. The default is "<!--more-->".
 var SummaryDivider = []byte("<!--more-->")
 
+// ContentSpec provides functionality to render markdown content.
 type ContentSpec struct {
 	blackfriday                map[string]interface{}
 	footnoteAnchorPrefix       string
@@ -50,6 +51,8 @@ type ContentSpec struct {
 	cfg config.Provider
 }
 
+// NewContentSpec returns a ContentSpec initialized
+// with the appropriate fields from the given config.Provider.
 func NewContentSpec(cfg config.Provider) *ContentSpec {
 	return &ContentSpec{
 		blackfriday:                cfg.GetStringMap("blackfriday"),

helpers/content_renderer.go

@@ -22,7 +22,10 @@ import (
 	"github.com/russross/blackfriday"
 )
 
+// LinkResolverFunc describes a custom function to resolve a given link.
 type LinkResolverFunc func(ref string) (string, error)
+
+// FileResolverFunc describes a custom function to resolve a given file path.
 type FileResolverFunc func(ref string) (string, error)
 
 // HugoHTMLRenderer wraps a blackfriday.Renderer, typically a blackfriday.Html
@@ -32,6 +35,8 @@ type HugoHTMLRenderer struct {
 	blackfriday.Renderer
 }
 
+// BlockCode renders a given text as a block of code.
+// Pygments is used if it is setup to handle code fences.
 func (r *HugoHTMLRenderer) BlockCode(out *bytes.Buffer, text []byte, lang string) {
 	if r.Cfg.GetBool("pygmentsCodeFences") && (lang != "" || r.Cfg.GetBool("pygmentsCodeFencesGuessSyntax")) {
 		opts := r.Cfg.GetString("pygmentsOptions")
@@ -84,13 +89,15 @@ func (r *HugoHTMLRenderer) List(out *bytes.Buffer, text func() bool, flags int)
 	}
 }
 
-// HugoMmarkHTMLRenderer wraps a mmark.Renderer, typically a mmark.html
-// Enabling Hugo to customise the rendering experience
+// HugoMmarkHTMLRenderer wraps a mmark.Renderer, typically a mmark.html,
+// enabling Hugo to customise the rendering experience.
 type HugoMmarkHTMLRenderer struct {
 	mmark.Renderer
 	Cfg config.Provider
 }
 
+// BlockCode renders a given text as a block of code.
+// Pygments is used if it is setup to handle code fences.
 func (r *HugoMmarkHTMLRenderer) BlockCode(out *bytes.Buffer, text []byte, lang string, caption []byte, subfigure bool, callouts bool) {
 	if r.Cfg.GetBool("pygmentsCodeFences") && (lang != "" || r.Cfg.GetBool("pygmentsCodeFencesGuessSyntax")) {
 		str := html.UnescapeString(string(text))

helpers/hugo.go

@@ -38,6 +38,7 @@ func (v HugoVersion) String() string {
 	return hugoVersion(v.Number, v.PatchLevel, v.Suffix)
 }
 
+// ParseHugoVersion parses a version string.
 func ParseHugoVersion(s string) (HugoVersion, error) {
 	var vv HugoVersion
 
@@ -53,6 +54,8 @@ func ParseHugoVersion(s string) (HugoVersion, error) {
 	return vv, nil
 }
 
+// MustParseHugoVersion parses a version string
+// and panics if any error occurs.
 func MustParseHugoVersion(s string) HugoVersion {
 	vv, err := ParseHugoVersion(s)
 	if err != nil {
@@ -72,7 +75,7 @@ func (v HugoVersion) Next() HugoVersion {
 	return HugoVersion{Number: v.Number + 0.01}
 }
 
-// Pre returns the previous Hugo release version.
+// Prev returns the previous Hugo release version.
 func (v HugoVersion) Prev() HugoVersion {
 	return HugoVersion{Number: v.Number - 0.01}
 }

helpers/language.go

@@ -35,6 +35,7 @@ var globalOnlySettings = map[string]bool{
 	strings.ToLower("multilingual"):                   true,
 }
 
+// Language manages specific-language configuration.
 type Language struct {
 	Lang         string
 	LanguageName string
@@ -50,10 +51,13 @@ func (l *Language) String() string {
 	return l.Lang
 }
 
+// NewLanguage creates a new language.
 func NewLanguage(lang string, cfg config.Provider) *Language {
 	return &Language{Lang: lang, Cfg: cfg, params: make(map[string]interface{})}
 }
 
+// NewDefaultLanguage creates the default language for a config.Provider.
+// If not otherwise specified the default is "en".
 func NewDefaultLanguage(cfg config.Provider) *Language {
 	defaultLang := cfg.GetString("defaultContentLanguage")
 
@@ -64,8 +68,11 @@ func NewDefaultLanguage(cfg config.Provider) *Language {
 	return NewLanguage(defaultLang, cfg)
 }
 
+// Languages is a sortable list of languages.
 type Languages []*Language
 
+// NewLanguages creates a sorted list of languages.
+// NOTE: function is currently unused.
 func NewLanguages(l ...*Language) Languages {
 	languages := make(Languages, len(l))
 	for i := 0; i < len(l); i++ {
@@ -79,6 +86,7 @@ func (l Languages) Len() int           { return len(l) }
 func (l Languages) Less(i, j int) bool { return l[i].Weight < l[j].Weight }
 func (l Languages) Swap(i, j int)      { l[i], l[j] = l[j], l[i] }
 
+// Params retunrs language-specific params merged with the global params.
 func (l *Language) Params() map[string]interface{} {
 	l.paramsInit.Do(func() {
 		// Merge with global config.

helpers/path.go

@@ -32,6 +32,7 @@ var (
 	// ErrThemeUndefined is returned when a theme has not be defined by the user.
 	ErrThemeUndefined = errors.New("no theme set")
 
+	// ErrWalkRootTooShort is returned when the root specified for a file walk is shorter than 4 characters.
 	ErrWalkRootTooShort = errors.New("Path too short. Stop walking.")
 )
 
@@ -480,7 +481,7 @@ func FindCWD() (string, error) {
 
 // SymbolicWalk is like filepath.Walk, but it supports the root being a
 // symbolic link. It will still not follow symbolic links deeper down in
-// the file structure
+// the file structure.
 func SymbolicWalk(fs afero.Fs, root string, walker filepath.WalkFunc) error {
 
 	// Sanity check