Some godoc adjustments

This commit is contained in:
Bjørn Erik Pedersen 2022-04-21 10:59:13 +02:00
parent 05b45c35c8
commit 9a888c243a
8 changed files with 71 additions and 18 deletions

View file

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

View file

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

View file

@ -33,19 +33,44 @@ var smc = newMenuCache()
// MenuEntry represents a menu item defined in either Page front matter // MenuEntry represents a menu item defined in either Page front matter
// or in the site config. // or in the site config.
type MenuEntry struct { 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 { func (m *MenuEntry) URL() string {
@ -170,6 +195,7 @@ func (m *MenuEntry) MarshallMap(ime map[string]any) error {
return nil return nil
} }
// This is for internal use only.
func (m Menu) Add(me *MenuEntry) Menu { func (m Menu) Add(me *MenuEntry) Menu {
m = append(m, me) m = append(m, me)
// TODO(bep) // TODO(bep)
@ -271,6 +297,8 @@ func (m Menu) Reverse() Menu {
return menus return menus
} }
// Clone clones the menu entries.
// This is for internal use only.
func (m Menu) Clone() Menu { func (m Menu) Clone() Menu {
return append(Menu(nil), m...) return append(Menu(nil), m...)
} }

View file

@ -78,13 +78,30 @@ type ChildCareProvider interface {
// ContentProvider provides the content related values for a Page. // ContentProvider provides the content related values for a Page.
type ContentProvider interface { type ContentProvider interface {
Content() (any, error) Content() (any, error)
// Plain returns the Page Content stripped of HTML markup.
Plain() string Plain() string
// PlainWords returns a string slice from splitting Plain using https://pkg.go.dev/strings#Fields.
PlainWords() []string 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 Summary() template.HTML
// Truncated returns whether the Summary is truncated or not.
Truncated() bool Truncated() bool
// FuzzyWordCount returns the approximate number of words in the content.
FuzzyWordCount() int FuzzyWordCount() int
// WordCount returns the number of words in the content.
WordCount() int WordCount() int
// ReadingTime returns the reading time based on the length of plain text.
ReadingTime() int ReadingTime() int
// Len returns the length of the content.
Len() int Len() int
} }

View file

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

View file

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

View file

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

View file

@ -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. // Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
// The provided collator will be used for string comparisons. // 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 { func (n *Namespace) LtCollate(collator *langs.Collator, first any, others ...any) bool {
n.checkComparisonArgCount(1, others...) n.checkComparisonArgCount(1, others...)
for _, other := range others { for _, other := range others {