diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-12-30 09:20:58 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-01-04 18:01:26 +0100 |
commit | e402d91ee199afcace8ae75da6c3587bb8089ace (patch) | |
tree | a0f51de9707ed03aa1a3d7a9195fd9d0fceab108 | |
parent | 3c51625c7152abca7e035fae15fc6807ca21cc86 (diff) |
Misc doc, code refactoring to improve documentation
47 files changed, 238 insertions, 95 deletions
diff --git a/codegen/methods.go b/codegen/methods.go index 9bc80cc3e..65a7cc2b7 100644 --- a/codegen/methods.go +++ b/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. diff --git a/commands/config.go b/commands/config.go index 7fda2d40e..a5d8aab22 100644 --- a/commands/config.go +++ b/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 diff --git a/common/docs.go b/common/docs.go new file mode 100644 index 000000000..041a62a01 --- /dev/null +++ b/common/docs.go @@ -0,0 +1,2 @@ +// Package common provides common helper functionality for Hugo. +package common diff --git a/common/maps/scratch.go b/common/maps/scratch.go index d4745d27c..e9f412540 100644 --- a/common/maps/scratch.go +++ b/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 } diff --git a/common/paths/path.go b/common/paths/path.go index 3a7f3e790..11d221bb1 100644 --- a/common/paths/path.go +++ b/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) +} diff --git a/common/text/position.go b/common/text/position.go index cc1eda354..eb9de5624 100644 --- a/common/text/position.go +++ b/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 } diff --git a/config/security/whitelist.go b/config/security/whitelist.go index 0d2c187c6..4aff9e9c4 100644 --- a/config/security/whitelist.go +++ b/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) diff --git a/hugofs/fileinfo.go b/hugofs/fileinfo.go index 1d46a7464..c33997278 100644 --- a/hugofs/fileinfo.go +++ b/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 } diff --git a/hugolib/content_map_page.go b/hugolib/content_map_page.go index 7e6b6e670..d8f28286c 100644 --- a/hugolib/content_map_page.go +++ b/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 }) diff --git a/hugolib/gitinfo.go b/hugolib/gitinfo.go index 17717ed52..d051b10bc 100644 --- a/hugolib/gitinfo.go +++ b/hugolib/gitinfo.go @@ -20,6 +20,7 @@ import ( "github.com/bep/gitmap" "github.com/gohugoio/hugo/config" "github.com/gohugoio/hugo/resources/page" + "github.com/gohugoio/hugo/source" ) type gitInfo struct { @@ -27,11 +28,14 @@ type gitInfo struct { 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) { diff --git a/hugolib/hugo_sites.go b/hugolib/hugo_sites.go index 6be26d60e..569c27be5 100644 --- a/hugolib/hugo_sites.go +++ b/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 diff --git a/hugolib/page.go b/hugolib/page.go index 5acfbc677..97f1ed351 100644 --- a/hugolib/page.go +++ b/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 } diff --git a/hugolib/page__common.go b/hugolib/page__common.go index 59f0bc776..0527a0682 100644 --- a/hugolib/page__common.go +++ b/hugolib/page__common.go @@ -16,7 +16,6 @@ package hugolib import ( "sync" - "github.com/bep/gitmap" "github.com/gohugoio/hugo/common/maps" "github.com/gohugoio/hugo/compare" "github.com/gohugoio/hugo/lazy" @@ -24,6 +23,7 @@ import ( "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 diff --git a/hugolib/page__meta.go b/hugolib/page__meta.go index daf989f42..8d2495ddc 100644 --- a/hugolib/page__meta.go +++ b/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 } diff --git a/hugolib/site.go b/hugolib/site.go index 8fb39a1ea..2ffc3a346 100644 --- a/hugolib/site.go +++ b/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() } diff --git a/langs/language.go b/langs/language.go index d6b30ec10..42aefda5e 100644 --- a/langs/language.go +++ b/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 ( diff --git a/markup/converter/hooks/hooks.go b/markup/converter/hooks/hooks.go index a59da939e..7eede0710 100644 --- a/markup/converter/hooks/hooks.go +++ b/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 } diff --git a/markup/highlight/highlight.go b/markup/highlight/highlight.go index 010c941f7..b74997700 100644 --- a/markup/highlight/highlight.go +++ b/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] } diff --git a/markup/markup.go b/markup/markup.go index 1345867f9..aefa50867 100644 --- a/markup/markup.go +++ b/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 ( diff --git a/media/mediaType.go b/media/mediaType.go index e47acb1e3..cdfb1c654 100644 --- a/media/mediaType.go +++ b/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 ( diff --git a/navigation/menu.go b/navigation/menu.go index 5e4996f39..cb280823c 100644 --- a/navigation/menu.go +++ b/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 ( diff --git a/navigation/menu_cache.go b/navigation/menu_cache.go index 6a3266431..4287ed875 100644 --- a/navigation/menu_cache.go +++ b/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 ( diff --git a/output/outputFormat.go b/output/outputFormat.go index 722079df9..0bc08e490 100644 --- a/output/outputFormat.go +++ b/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 { diff --git a/resources/docs.go b/resources/docs.go new file mode 100644 index 000000000..f992893da --- /dev/null +++ b/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 diff --git a/resources/images/exif/exif.go b/resources/images/exif/exif.go index 487f250d5..8df348b23 100644 --- a/resources/images/exif/exif.go +++ b/resources/images/exif/exif.go @@ -254,8 +254,10 @@ func init() { } } +// Tags is a map of EXIF tags. type Tags map[string]any +// UnmarshalJSON is for internal use only. func (v *Tags) UnmarshalJSON(b []byte) error { vv := make(map[string]any) if err := tcodec.Unmarshal(b, &vv); err != nil { @@ -267,6 +269,7 @@ func (v *Tags) UnmarshalJSON(b []byte) error { return nil } +// MarshalJSON is for internal use only. func (v Tags) MarshalJSON() ([]byte, error) { return tcodec.Marshal(v) } diff --git a/resources/images/image_resource.go b/resources/images/image_resource.go index 4e66b010c..846959006 100644 --- a/resources/images/image_resource.go +++ b/resources/images/image_resource.go |