Some godoc adjustments

diff --git a/compare/compare.go b/compare/compare.go
index a0d2b3239fc728bf3413e3c7f3cf50453bfd665d..de97690c7d409a8ef457e97d1af800460c84cb71 100644 (file)
--- a/compare/compare.go
+++ b/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
 }
 

diff --git a/identity/identity.go b/identity/identity.go
index 0527406756c34461291969e40cfc726e2d4715e7..9236f08769e37adba0264a2bc2119f53a49f0cbb 100644 (file)
--- a/identity/identity.go
+++ b/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
 }
 

diff --git a/navigation/menu.go b/navigation/menu.go
index 2693f0ac8cc6aae5ce47331b6480b74f040d0302..b9fb46e70385163ccdf7408689b82fde247eec0f 100644 (file)
--- a/navigation/menu.go
+++ b/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.
-       Page          Page
-       PageRef       string // The path to the page, only relevant for site config.
-       Name          string
-       Menu          string
-       Identifier    string
-       title         string
-       Pre           template.HTML
-       Post          template.HTML
-       Weight        int
-       Parent        string
-       Children      Menu
-       Params        maps.Params
+       // The URL value from front matter / config.
+       ConfiguredURL string
+
+       // The Page connected to this menu entry.
+       Page Page
+
+       // The path to the page, only relevant for menus defined in site config.
+       PageRef string
+
+       // The name of the menu entry.
+       Name string
+
+       // 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...)
 }

diff --git a/resources/page/page.go b/resources/page/page.go
index 3c58dbb665a6f56944415232d471aa1b4a6ac839..5ddacc8a6096bbf25d7b636ca4d95234653f6671 100644 (file)
--- a/resources/page/page.go
+++ b/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
 }
 

diff --git a/resources/page/pages.go b/resources/page/pages.go
index e0f133500f442c94fc65036c0912f4e43d7a387e..4db6a4f684b9e84233a99ead4f7680370987eb08 100644 (file)
--- a/resources/page/pages.go
+++ b/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{}
+)

diff --git a/resources/resource/resources.go b/resources/resource/resources.go
index 428decf84874ba7fe3977142cfc07f4681c14069..a888d6fb4ba78cfc25a9bfab3c402429c549cee5 100644 (file)
--- a/resources/resource/resources.go
+++ b/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
 }
 

diff --git a/resources/resource/resourcetypes.go b/resources/resource/resourcetypes.go
index ae076ed9a01bf162d19dca2101098d9d6b1750eb..a4f820188c1c70016dcf9e181e85cdd267dd19e2 100644 (file)
--- a/resources/resource/resourcetypes.go
+++ b/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)
 }
 

diff --git a/tpl/compare/compare.go b/tpl/compare/compare.go
index 3e9730dadba3f0b70a1f5d7e2dbb412977e95cc5..9905003b23c24e8d2465b11810b420dc6f765bf8 100644 (file)
--- a/tpl/compare/compare.go
+++ b/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 {