commit 9a888c243adc2be4b630f29eac7def742803d8a4
parent 05b45c35c8067b7c4a6c99fec64f124739d2e7fd
Author: Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
Date: Thu, 21 Apr 2022 10:59:13 +0200
Some godoc adjustments
Diffstat:
8 files changed, 71 insertions(+), 18 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 {