Some godoc adjustments

compare/compare.go

@@ -17,12 +17,15 @@ package compare
 // The semantics of equals is that the two value are interchangeable
 // in the Hugo templates.
 type Eqer interface {
+	// Eq returns whether this value is equal to the other.
+	// This is for internal use.
 	Eq(other any) bool
 }
 
 // ProbablyEqer is an equal check that may return false positives, but never
 // a false negative.
 type ProbablyEqer interface {
+	// For internal use.
 	ProbablyEq(other any) bool
 }
 

identity/identity.go

@@ -109,6 +109,7 @@ func (id KeyValueIdentity) Name() string {
 
 // Provider provides the hashable Identity.
 type Provider interface {
+	// GetIdentity is for internal use.
 	GetIdentity() Identity
 }
 

navigation/menu.go

@@ -33,19 +33,44 @@ var smc = newMenuCache()
 // MenuEntry represents a menu item defined in either Page front matter
 // or in the site config.
 type MenuEntry struct {
-	ConfiguredURL string // The URL value from front matter / config.
+	// The URL value from front matter / config.
-	Page          Page
+	ConfiguredURL string
-	PageRef       string // The path to the page, only relevant for site config.
+
-	Name          string
+	// The Page connected to this menu entry.
-	Menu          string
+	Page Page
-	Identifier    string
+
-	title         string
+	// The path to the page, only relevant for menus defined in site config.
-	Pre           template.HTML
+	PageRef string
-	Post          template.HTML
+
-	Weight        int
+	// The name of the menu entry.
-	Parent        string
+	Name string
-	Children      Menu
+
-	Params        maps.Params
+	// The menu containing this menu entry.
+	Menu string
+
+	// Used to identify this menu entry.
+	Identifier string
+
+	title string
+
+	// If set, will be rendered before this menu entry.
+	Pre template.HTML
+
+	// If set, will be rendered after this menu entry.
+	Post template.HTML
+
+	// The weight of this menu entry, used for sorting.
+	// Set to a non-zero value, negative or positive.
+	Weight int
+
+	// Identifier of the parent menu entry.
+	Parent string
+
+	// Child entries.
+	Children Menu
+
+	// User defined params.
+	Params maps.Params
 }
 
 func (m *MenuEntry) URL() string {
@@ -170,6 +195,7 @@ func (m *MenuEntry) MarshallMap(ime map[string]any) error {
 	return nil
 }
 
+// This is for internal use only.
 func (m Menu) Add(me *MenuEntry) Menu {
 	m = append(m, me)
 	// TODO(bep)
@@ -271,6 +297,8 @@ func (m Menu) Reverse() Menu {
 	return menus
 }
 
+// Clone clones the menu entries.
+// This is for internal use only.
 func (m Menu) Clone() Menu {
 	return append(Menu(nil), m...)
 }

resources/page/page.go

@@ -78,13 +78,30 @@ type ChildCareProvider interface {
 // ContentProvider provides the content related values for a Page.
 type ContentProvider interface {
 	Content() (any, error)
+
+	// Plain returns the Page Content stripped of HTML markup.
 	Plain() string
+
+	// PlainWords returns a string slice from splitting Plain using https://pkg.go.dev/strings#Fields.
 	PlainWords() []string
+
+	// Summary returns a generated summary of the content.
+	// The breakpoint can be set manually by inserting a summary separator in the source file.
 	Summary() template.HTML
+
+	// Truncated returns whether the Summary  is truncated or not.
 	Truncated() bool
+
+	// FuzzyWordCount returns the approximate number of words in the content.
 	FuzzyWordCount() int
+
+	// WordCount returns the number of words in the content.
 	WordCount() int
+
+	// ReadingTime returns the reading time based on the length of plain text.
 	ReadingTime() int
+
+	// Len returns the length of the content.
 	Len() int
 }
 

resources/page/pages.go

@@ -22,11 +22,6 @@ import (
 	"github.com/gohugoio/hugo/resources/resource"
 )
 
-var (
-	_ resource.ResourcesConverter = Pages{}
-	_ compare.ProbablyEqer        = Pages{}
-)
-
 // Pages is a slice of pages. This is the most common list type in Hugo.
 type Pages []Page
 
@@ -149,3 +144,8 @@ func (ps Pages) removeFirstIfFound(p Page) Pages {
 // PagesFactory somehow creates some Pages.
 // We do a lot of lazy Pages initialization in Hugo, so we need a type.
 type PagesFactory func() Pages
+
+var (
+	_ resource.ResourcesConverter = Pages{}
+	_ compare.ProbablyEqer        = Pages{}
+)

resources/resource/resources.go

@@ -30,6 +30,7 @@ type Resources []Resource
 // var _ resource.ResourceFinder = (*Namespace)(nil)
 // ResourcesConverter converts a given slice of Resource objects to Resources.
 type ResourcesConverter interface {
+	// For internal use.
 	ToResources() Resources
 }
 

resources/resource/resourcetypes.go

@@ -155,7 +155,9 @@ type ResourceDataProvider interface {
 // different language.
 type ResourcesLanguageMerger interface {
 	MergeByLanguage(other Resources) Resources
+
 	// Needed for integration with the tpl package.
+	// For internal use.
 	MergeByLanguageInterface(other any) (any, error)
 }
 

tpl/compare/compare.go

@@ -190,6 +190,7 @@ func (n *Namespace) Le(first any, others ...any) bool {
 
 // Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
 // The provided collator will be used for string comparisons.
+// This is for internal use.
 func (n *Namespace) LtCollate(collator *langs.Collator, first any, others ...any) bool {
 	n.checkComparisonArgCount(1, others...)
 	for _, other := range others {