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.

create/content_template_handler.go

@@ -49,6 +49,7 @@ type ArchetypeFileData struct {
 }
 
 const (
+	// ArchetypeTemplateTemplate is used as inital template when adding an archetype template.
 	ArchetypeTemplateTemplate = `---
 title: "{{ replace .TranslationBaseName "-" " " | title }}"
 date: {{ .Date }}
@@ -123,7 +124,7 @@ func executeArcheTypeAsTemplate(s *hugolib.Site, kind, targetPath, archetypeFile
 
 	if !bytes.Contains(archetypeContent, []byte("date")) || !bytes.Contains(archetypeContent, []byte("title")) {
 		// TODO(bep) remove some time in the future.
-		s.Log.FEEDBACK.Println(fmt.Sprintf(`WARNING: date and/or title missing from archetype file %q. 
+		s.Log.FEEDBACK.Println(fmt.Sprintf(`WARNING: date and/or title missing from archetype file %q.
 From Hugo 0.24 this must be provided in the archetype file itself, if needed. Example:
 %s
 `, archetypeFilename, ArchetypeTemplateTemplate))

deps/deps.go

@@ -14,7 +14,7 @@ import (
 )
 
 // Deps holds dependencies used by many.
-// There will be normally be only one instance of deps in play
+// There will be normally only one instance of deps in play
 // at a given time, i.e. one per Site built.
 type Deps struct {
 	// The logger to use.
@@ -55,10 +55,12 @@ type ResourceProvider interface {
 	Clone(deps *Deps) error
 }
 
+// TemplateHandler returns the used tpl.TemplateFinder as tpl.TemplateHandler.
 func (d *Deps) TemplateHandler() tpl.TemplateHandler {
 	return d.Tmpl.(tpl.TemplateHandler)
 }
 
+// LoadResources loads translations and templates.
 func (d *Deps) LoadResources() error {
 	// Note that the translations need to be loaded before the templates.
 	if err := d.translationProvider.Update(d); err != nil {
@@ -76,6 +78,9 @@ func (d *Deps) LoadResources() error {
 	return nil
 }
 
+// New initializes a Dep struct.
+// Defaults are set for nil values,
+// but TemplateProvider, TranslationProvider and Language are always required.
 func New(cfg DepsCfg) (*Deps, error) {
 	var (
 		logger = cfg.Logger

docshelper/docs.go

@@ -19,14 +19,19 @@ import (
 	"encoding/json"
 )
 
+// DocProviders contains all DocProviders added to the system.
 var DocProviders = make(map[string]DocProvider)
 
+// AddDocProvider adds or updates the DocProvider for a given name.
 func AddDocProvider(name string, provider DocProvider) {
 	DocProviders[name] = provider
 }
 
+// DocProvider is used to save arbitrary JSON data
+// used for the generation of the documentation.
 type DocProvider func() map[string]interface{}
 
+// MarshalJSON returns a JSON representation of the DocProvider.
 func (d DocProvider) MarshalJSON() ([]byte, error) {
 	return json.MarshalIndent(d(), "", "  ")
 }

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

hugofs/fs.go

@@ -22,6 +22,8 @@ import (
 // Os points to an Os Afero file system.
 var Os = &afero.OsFs{}
 
+// Fs abstracts the file system to separate source and destination file systems
+// and allows both to be mocked for testing.
 type Fs struct {
 	// Source is Hugo's source file system.
 	Source afero.Fs
@@ -30,6 +32,7 @@ type Fs struct {
 	Destination afero.Fs
 
 	// Os is an OS file system.
+	// NOTE: Field is currently unused.
 	Os afero.Fs
 
 	// WorkingDir is a read-only file system

hugolib/handler_base.go

@@ -17,21 +17,25 @@ import (
 	"github.com/gohugoio/hugo/source"
 )
 
+// Handler is used for processing files of a specific type.
 type Handler interface {
 	FileConvert(*source.File, *Site) HandledResult
 	PageConvert(*Page) HandledResult
 	Read(*source.File, *Site) HandledResult
 	Extensions() []string
 }
 
+// Handle identifies functionality assosiated with certain file extentions.
 type Handle struct {
 	extensions []string
 }
 
+// Extensions returns a list of extentions.
 func (h Handle) Extensions() []string {
 	return h.extensions
 }
 
+// HandledResult describes the results of a file handling operation.
 type HandledResult struct {
 	page *Page
 	file *source.File
@@ -55,6 +59,7 @@ func (h HandledResult) String() string {
 	return h.Error()
 }
 
+// Page returns the affected page.
 func (h HandledResult) Page() *Page {
 	return h.page
 }

hugolib/handler_meta.go

@@ -23,6 +23,7 @@ import (
 
 var handlers []Handler
 
+// MetaHandler abstracts reading and converting functionality of a Handler.
 type MetaHandler interface {
 	// Read the Files in and register
 	Read(*source.File, *Site, HandleResults)
@@ -33,14 +34,18 @@ type MetaHandler interface {
 	Handle() Handler
 }
 
+// HandledResults is a channel for HandledResult.
 type HandleResults chan<- HandledResult
 
+// NewMetaHandler creates a MetaHandle for a given extention.
 func NewMetaHandler(in string) *MetaHandle {
 	x := &MetaHandle{ext: in}
 	x.Handler()
 	return x
 }
 
+// MetaHandle is a generic MetaHandler that internally uses
+// the globally registered handlers for handling specific file types.
 type MetaHandle struct {
 	handler Handler
 	ext     string
@@ -55,6 +60,7 @@ func (mh *MetaHandle) Read(f *source.File, s *Site, results HandleResults) {
 	results <- HandledResult{err: errors.New("No handler found"), file: f}
 }
 
+// Convert handles the convertion of files and pages.
 func (mh *MetaHandle) Convert(i interface{}, s *Site, results HandleResults) {
 	h := mh.Handler()
 
@@ -78,6 +84,7 @@ func (mh *MetaHandle) Convert(i interface{}, s *Site, results HandleResults) {
 	}
 }
 
+// Handler finds the registered handler for the used extention.
 func (mh *MetaHandle) Handler() Handler {
 	if mh.handler == nil {
 		mh.handler = FindHandler(mh.ext)
@@ -90,6 +97,7 @@ func (mh *MetaHandle) Handler() Handler {
 	return mh.handler
 }
 
+// FindHandler finds a Handler in the globally registered handlers.
 func FindHandler(ext string) Handler {
 	for _, h := range Handlers() {
 		if HandlerMatch(h, ext) {
@@ -99,6 +107,7 @@ func FindHandler(ext string) Handler {
 	return nil
 }
 
+// HandlerMatch checks if the given extention matches.
 func HandlerMatch(h Handler, ext string) bool {
 	for _, x := range h.Extensions() {
 		if ext == x {
@@ -108,10 +117,12 @@ func HandlerMatch(h Handler, ext string) bool {
 	return false
 }
 
+// RegisterHandler adds a handler to the globally registered ones.
 func RegisterHandler(h Handler) {
 	handlers = append(handlers, h)
 }
 
+// Handlers returns the globally registered handlers.
 func Handlers() []Handler {
 	return handlers
 }

hugolib/multilingual.go

@@ -26,6 +26,7 @@ import (
 	"github.com/spf13/cast"
 )
 
+// Multilingual manages the all languages used in a multilingual site.
 type Multilingual struct {
 	Languages helpers.Languages
 
@@ -35,6 +36,7 @@ type Multilingual struct {
 	langMapInit sync.Once
 }
 
+// Language returns the Language assosiated with the given string.
 func (ml *Multilingual) Language(lang string) *helpers.Language {
 	ml.langMapInit.Do(func() {
 		ml.langMap = make(map[string]*helpers.Language)

hugolib/page_output.go

@@ -179,7 +179,7 @@ func (p *Page) checkRender() bool {
 // OutputFormats holds a list of the relevant output formats for a given resource.
 type OutputFormats []*OutputFormat
 
-// And OutputFormat links to a representation of a resource.
+// OutputFormat links to a representation of a resource.
 type OutputFormat struct {
 	// Rel constains a value that can be used to construct a rel link.
 	// This is value is fetched from the output format definition.
@@ -227,7 +227,7 @@ func newOutputFormat(p *Page, f output.Format) *OutputFormat {
 	return &OutputFormat{Rel: rel, f: f, p: p}
 }
 
-// OutputFormats gives the alternative output formats for this PageOutput.
+// AlternativeOutputFormats gives the alternative output formats for this PageOutput.
 // Note that we use the term "alternative" and not "alternate" here, as it
 // does not necessarily replace the other format, it is an alternative representation.
 func (p *PageOutput) AlternativeOutputFormats() (OutputFormats, error) {
@@ -266,7 +266,7 @@ func (o *OutputFormat) Permalink() string {
 	return perm
 }
 
-// Permalink returns the relative permalink to this output format.
+// RelPermalink returns the relative permalink to this output format.
 func (o *OutputFormat) RelPermalink() string {
 	rel := o.p.createRelativePermalinkForOutputFormat(o.f)
 	return o.p.s.PathSpec.PrependBasePath(rel)