Misc doc, code refactoring to improve documentation

codegen/methods.go

@@ -452,12 +452,16 @@ func collectMethodsRecursive(pkg string, f []*ast.Field) []string {
 		}
 
 		if ident, ok := m.Type.(*ast.Ident); ok && ident.Obj != nil {
-			// Embedded interface
-			methodNames = append(
-				methodNames,
-				collectMethodsRecursive(
-					pkg,
-					ident.Obj.Decl.(*ast.TypeSpec).Type.(*ast.InterfaceType).Methods.List)...)
+			switch tt := ident.Obj.Decl.(*ast.TypeSpec).Type.(type) {
+			case *ast.InterfaceType:
+				// Embedded interface
+				methodNames = append(
+					methodNames,
+					collectMethodsRecursive(
+						pkg,
+						tt.Methods.List)...)
+			}
+
 		} else {
 			// Embedded, but in a different file/package. Return the
 			// package.Name and deal with that later.

commands/config.go

@@ -126,6 +126,7 @@ type modMount struct {
 	Lang   string `json:"lang,omitempty"`
 }
 
+// MarshalJSON is for internal use only.
 func (m *modMounts) MarshalJSON() ([]byte, error) {
 	var mounts []modMount
 

common/docs.go

@@ -0,0 +1,2 @@
+// Package common provides common helper functionality for Hugo.
+package common

common/maps/scratch.go

@@ -30,6 +30,7 @@ type Scratch struct {
 
 // Scratcher provides a scratching service.
 type Scratcher interface {
+	// Scratch returns a "scratch pad" that can be used to store state.
 	Scratch() *Scratch
 }
 

common/paths/path.go

@@ -263,3 +263,14 @@ func (n NamedSlice) String() string {
 	}
 	return fmt.Sprintf("%s%s{%s}", n.Name, FilePathSeparator, strings.Join(n.Slice, ","))
 }
+
+// DirFile holds the result from path.Split.
+type DirFile struct {
+	Dir  string
+	File string
+}
+
+// Used in test.
+func (df DirFile) String() string {
+	return fmt.Sprintf("%s|%s", df.Dir, df.File)
+}

common/text/position.go

@@ -24,6 +24,8 @@ import (
 // Positioner represents a thing that knows its position in a text file or stream,
 // typically an error.
 type Positioner interface {
+	// Position returns the current position.
+	// Useful in error logging, e.g. {{ errorf "error in code block: %s" .Position }}.
 	Position() Position
 }
 

config/security/whitelist.go

@@ -33,6 +33,7 @@ type Whitelist struct {
 	patternsStrings []string
 }
 
+// MarshalJSON is for internal use only.
 func (w Whitelist) MarshalJSON() ([]byte, error) {
 	if w.acceptNone {
 		return json.Marshal(acceptNoneKeyword)

hugofs/fileinfo.go

@@ -130,6 +130,7 @@ func (f *FileMeta) JoinStat(name string) (FileMetaInfo, error) {
 
 type FileMetaInfo interface {
 	os.FileInfo
+	// Meta is for internal use.
 	Meta() *FileMeta
 }
 

hugolib/content_map_page.go

@@ -266,7 +266,7 @@ func (m *pageMap) newResource(fim hugofs.FileMetaInfo, owner *pageState) (resour
 }
 
 func (m *pageMap) createSiteTaxonomies() error {
-	m.s.taxonomies = make(TaxonomyList)
+	m.s.taxonomies = make(page.TaxonomyList)
 	var walkErr error
 	m.taxonomies.Walk(func(s string, v any) bool {
 		n := v.(*contentNode)
@@ -275,7 +275,7 @@ func (m *pageMap) createSiteTaxonomies() error {
 		viewName := t.name
 
 		if t.termKey == "" {
-			m.s.taxonomies[viewName.plural] = make(Taxonomy)
+			m.s.taxonomies[viewName.plural] = make(page.Taxonomy)
 		} else {
 			taxonomy := m.s.taxonomies[viewName.plural]
 			if taxonomy == nil {
@@ -285,7 +285,7 @@ func (m *pageMap) createSiteTaxonomies() error {
 			m.taxonomyEntries.WalkPrefix(s, func(ss string, v any) bool {
 				b2 := v.(*contentNode)
 				info := b2.viewInfo
-				taxonomy.add(info.termKey, page.NewWeightedPage(info.weight, info.ref.p, n.p))
+				taxonomy[info.termKey] = append(taxonomy[info.termKey], page.NewWeightedPage(info.weight, info.ref.p, n.p))
 
 				return false
 			})

hugolib/gitinfo.go

@@ -20,18 +20,22 @@ import (
 	"github.com/bep/gitmap"
 	"github.com/gohugoio/hugo/config"
 	"github.com/gohugoio/hugo/resources/page"
+	"github.com/gohugoio/hugo/source"
 )
 
 type gitInfo struct {
 	contentDir string
 	repo       *gitmap.GitRepo
 }
 
-func (g *gitInfo) forPage(p page.Page) *gitmap.GitInfo {
+func (g *gitInfo) forPage(p page.Page) source.GitInfo {
 	name := strings.TrimPrefix(filepath.ToSlash(p.File().Filename()), g.contentDir)
 	name = strings.TrimPrefix(name, "/")
-
-	return g.repo.Files[name]
+	gi, found := g.repo.Files[name]
+	if !found {
+		return source.GitInfo{}
+	}
+	return source.NewGitInfo(*gi)
 }
 
 func newGitInfo(cfg config.Provider) (*gitInfo, error) {

hugolib/hugo_sites.go

@@ -41,7 +41,6 @@ import (
 
 	"github.com/gohugoio/hugo/source"
 
-	"github.com/bep/gitmap"
 	"github.com/gohugoio/hugo/config"
 
 	"github.com/gohugoio/hugo/publisher"
@@ -202,13 +201,13 @@ func (h *HugoSites) Data() map[string]any {
 	return h.data
 }
 
-func (h *HugoSites) gitInfoForPage(p page.Page) (*gitmap.GitInfo, error) {
+func (h *HugoSites) gitInfoForPage(p page.Page) (source.GitInfo, error) {
 	if _, err := h.init.gitInfo.Do(); err != nil {
-		return nil, err
+		return source.GitInfo{}, err
 	}
 
 	if h.gitInfo == nil {
-		return nil, nil
+		return source.GitInfo{}, nil
 	}
 
 	return h.gitInfo.forPage(p), nil

hugolib/page.go

@@ -31,8 +31,6 @@ import (
 
 	"github.com/gohugoio/hugo/hugofs/files"
 
-	"github.com/bep/gitmap"
-
 	"github.com/gohugoio/hugo/helpers"
 
 	"github.com/gohugoio/hugo/common/herrors"
@@ -150,7 +148,7 @@ func (p *pageState) GetIdentity() identity.Identity {
 	return identity.NewPathIdentity(files.ComponentFolderContent, filepath.FromSlash(p.Pathc()))
 }
 
-func (p *pageState) GitInfo() *gitmap.GitInfo {
+func (p *pageState) GitInfo() source.GitInfo {
 	return p.gitInfo
 }
 

hugolib/page__common.go

@@ -16,14 +16,14 @@ package hugolib
 import (
 	"sync"
 
-	"github.com/bep/gitmap"
 	"github.com/gohugoio/hugo/common/maps"
 	"github.com/gohugoio/hugo/compare"
 	"github.com/gohugoio/hugo/lazy"
 	"github.com/gohugoio/hugo/navigation"
 	"github.com/gohugoio/hugo/output"
 	"github.com/gohugoio/hugo/resources/page"
 	"github.com/gohugoio/hugo/resources/resource"
+	"github.com/gohugoio/hugo/source"
 )
 
 type treeRefProvider interface {
@@ -106,7 +106,7 @@ type pageCommon struct {
 	shortcodeState *shortcodeHandler
 
 	// Set if feature enabled and this is in a Git repo.
-	gitInfo    *gitmap.GitInfo
+	gitInfo    source.GitInfo
 	codeowners []string
 
 	// Positional navigation

hugolib/page__meta.go

@@ -404,7 +404,7 @@ func (pm *pageMeta) setMetadata(parentBucket *pagesMapBucket, p *pageState, fron
 	}
 
 	var gitAuthorDate time.Time
-	if p.gitInfo != nil {
+	if !p.gitInfo.IsZero() {
 		gitAuthorDate = p.gitInfo.AuthorDate
 	}
 

hugolib/site.go

@@ -110,9 +110,9 @@ type Site struct {
 
 	*PageCollections
 
-	taxonomies TaxonomyList
+	taxonomies page.TaxonomyList
 
-	Sections Taxonomy
+	Sections page.Taxonomy
 	Info     *SiteInfo
 
 	language   *langs.Language
@@ -172,7 +172,7 @@ type Site struct {
 	init *siteInit
 }
 
-func (s *Site) Taxonomies() TaxonomyList {
+func (s *Site) Taxonomies() page.TaxonomyList {
 	s.init.taxonomies.Do()
 	return s.taxonomies
 }
@@ -708,7 +708,7 @@ func (s *SiteInfo) Menus() navigation.Menus {
 }
 
 // TODO(bep) type
-func (s *SiteInfo) Taxonomies() any {
+func (s *SiteInfo) Taxonomies() page.TaxonomyList {
 	return s.s.Taxonomies()
 }
 

langs/language.go

@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package langs contains the language related types and function.
 package langs
 
 import (

markup/converter/hooks/hooks.go

@@ -26,30 +26,56 @@ import (
 var _ AttributesOptionsSliceProvider = (*attributes.AttributesHolder)(nil)
 
 type AttributesProvider interface {
+	// Attributes passed in from Markdown (e.g. { attrName1=attrValue1 attrName2="attr Value 2" }).
 	Attributes() map[string]any
 }
 
 type LinkContext interface {
+	// The Page being rendered.
 	Page() any
+
+	// The link URL.
 	Destination() string
+
+	// The link title attribute.
 	Title() string
+
+	// The rendered (HTML) text.
 	Text() hstring.RenderedString
+
+	// The plain variant of Text.
 	PlainText() string
 }
 
 type ImageLinkContext interface {
 	LinkContext
+
+	// Returns true if this is a standalone image and the config option
+	// markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
 	IsBlock() bool
+
+	// Zero-based ordinal for all the images in the current document.
 	Ordinal() int
 }
 
+// CodeblockContext is the context passed to a code block render hook.
 type CodeblockContext interface {
 	AttributesProvider
 	text.Positioner
+
+	// Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.
 	Options() map[string]any
+
+	// The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.
 	Type() string
+
+	// The text between the code fences.
 	Inner() string
+
+	// Zero-based ordinal for all code blocks in the current document.
 	Ordinal() int
+
+	// The owning Page.
 	Page() any
 }
 

markup/highlight/highlight.go

@@ -157,10 +157,12 @@ type HightlightResult struct {
 	highlighted template.HTML
 }
 
+// Wrapped returns the highlighted code wrapped in a <div>, <pre> and <code> tag.
 func (h HightlightResult) Wrapped() template.HTML {
 	return h.highlighted
 }
 
+// Inner returns the highlighted code without the wrapping <div>, <pre> and <code> tag, suitable for inline use.
 func (h HightlightResult) Inner() template.HTML {
 	return h.highlighted[h.innerLow:h.innerHigh]
 }

markup/markup.go

@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package markup contains the markup handling (e.g. Markdown).
 package markup
 
 import (

media/mediaType.go

@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package media containes Media Type (MIME type) related types and functions.
 package media
 
 import (

navigation/menu.go

@@ -1,4 +1,4 @@
-// Copyright 2019 The Hugo Authors. All rights reserved.
+// Copyright 2023 The Hugo Authors. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package navigation provides the menu functionality.
 package navigation
 
 import (

navigation/menu_cache.go

@@ -10,7 +10,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
+
 package navigation
 
 import (

output/outputFormat.go

@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package output contains Output Format types and functions.
 package output
 
 import (
@@ -400,6 +401,7 @@ func (f Format) BaseFilename() string {
 }
 
 // MarshalJSON returns the JSON encoding of f.
+// For internal use only.
 func (f Format) MarshalJSON() ([]byte, error) {
 	type Alias Format
 	return json.Marshal(&struct {

resources/docs.go

@@ -0,0 +1,15 @@
+// Copyright 2023 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package resources contains Resource related types.
+package resources