Skip to content

Commit e402d91

Browse files
bepbep
committed
Misc doc, code refactoring to improve documentation
1 parent 3c51625 commit e402d91

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+238
-95
lines changed

‎codegen/methods.go

+10-6
Original file line numberDiff line numberDiff line change
@@ -452,12 +452,16 @@ func collectMethodsRecursive(pkg string, f []*ast.Field) []string {
452452
}
453453

454454
if ident, ok := m.Type.(*ast.Ident); ok && ident.Obj != nil {
455-
// Embedded interface
456-
methodNames = append(
457-
methodNames,
458-
collectMethodsRecursive(
459-
pkg,
460-
ident.Obj.Decl.(*ast.TypeSpec).Type.(*ast.InterfaceType).Methods.List)...)
455+
switch tt := ident.Obj.Decl.(*ast.TypeSpec).Type.(type) {
456+
case *ast.InterfaceType:
457+
// Embedded interface
458+
methodNames = append(
459+
methodNames,
460+
collectMethodsRecursive(
461+
pkg,
462+
tt.Methods.List)...)
463+
}
464+
461465
} else {
462466
// Embedded, but in a different file/package. Return the
463467
// package.Name and deal with that later.

‎commands/config.go

+1
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ type modMount struct {
126126
Lang string `json:"lang,omitempty"`
127127
}
128128

129+
// MarshalJSON is for internal use only.
129130
func (m *modMounts) MarshalJSON() ([]byte, error) {
130131
var mounts []modMount
131132

‎common/docs.go

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
// Package common provides common helper functionality for Hugo.
2+
package common

‎common/maps/scratch.go

+1
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ type Scratch struct {
3030

3131
// Scratcher provides a scratching service.
3232
type Scratcher interface {
33+
// Scratch returns a "scratch pad" that can be used to store state.
3334
Scratch() *Scratch
3435
}
3536

‎common/paths/path.go

+11
Original file line numberDiff line numberDiff line change
@@ -263,3 +263,14 @@ func (n NamedSlice) String() string {
263263
}
264264
return fmt.Sprintf("%s%s{%s}", n.Name, FilePathSeparator, strings.Join(n.Slice, ","))
265265
}
266+
267+
// DirFile holds the result from path.Split.
268+
type DirFile struct {
269+
Dir string
270+
File string
271+
}
272+
273+
// Used in test.
274+
func (df DirFile) String() string {
275+
return fmt.Sprintf("%s|%s", df.Dir, df.File)
276+
}

‎common/text/position.go

+2
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ import (
2424
// Positioner represents a thing that knows its position in a text file or stream,
2525
// typically an error.
2626
type Positioner interface {
27+
// Position returns the current position.
28+
// Useful in error logging, e.g. {{ errorf "error in code block: %s" .Position }}.
2729
Position() Position
2830
}
2931

‎config/security/whitelist.go

+1
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ type Whitelist struct {
3333
patternsStrings []string
3434
}
3535

36+
// MarshalJSON is for internal use only.
3637
func (w Whitelist) MarshalJSON() ([]byte, error) {
3738
if w.acceptNone {
3839
return json.Marshal(acceptNoneKeyword)

‎hugofs/fileinfo.go

+1
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ func (f *FileMeta) JoinStat(name string) (FileMetaInfo, error) {
130130

131131
type FileMetaInfo interface {
132132
os.FileInfo
133+
// Meta is for internal use.
133134
Meta() *FileMeta
134135
}
135136

‎hugolib/content_map_page.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ func (m *pageMap) newResource(fim hugofs.FileMetaInfo, owner *pageState) (resour
266266
}
267267

268268
func (m *pageMap) createSiteTaxonomies() error {
269-
m.s.taxonomies = make(TaxonomyList)
269+
m.s.taxonomies = make(page.TaxonomyList)
270270
var walkErr error
271271
m.taxonomies.Walk(func(s string, v any) bool {
272272
n := v.(*contentNode)
@@ -275,7 +275,7 @@ func (m *pageMap) createSiteTaxonomies() error {
275275
viewName := t.name
276276

277277
if t.termKey == "" {
278-
m.s.taxonomies[viewName.plural] = make(Taxonomy)
278+
m.s.taxonomies[viewName.plural] = make(page.Taxonomy)
279279
} else {
280280
taxonomy := m.s.taxonomies[viewName.plural]
281281
if taxonomy == nil {
@@ -285,7 +285,7 @@ func (m *pageMap) createSiteTaxonomies() error {
285285
m.taxonomyEntries.WalkPrefix(s, func(ss string, v any) bool {
286286
b2 := v.(*contentNode)
287287
info := b2.viewInfo
288-
taxonomy.add(info.termKey, page.NewWeightedPage(info.weight, info.ref.p, n.p))
288+
taxonomy[info.termKey] = append(taxonomy[info.termKey], page.NewWeightedPage(info.weight, info.ref.p, n.p))
289289

290290
return false
291291
})

‎hugolib/gitinfo.go

+7-3
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,22 @@ import (
2020
"github.com/bep/gitmap"
2121
"github.com/gohugoio/hugo/config"
2222
"github.com/gohugoio/hugo/resources/page"
23+
"github.com/gohugoio/hugo/source"
2324
)
2425

2526
type gitInfo struct {
2627
contentDir string
2728
repo *gitmap.GitRepo
2829
}
2930

30-
func (g *gitInfo) forPage(p page.Page) *gitmap.GitInfo {
31+
func (g *gitInfo) forPage(p page.Page) source.GitInfo {
3132
name := strings.TrimPrefix(filepath.ToSlash(p.File().Filename()), g.contentDir)
3233
name = strings.TrimPrefix(name, "/")
33-
34-
return g.repo.Files[name]
34+
gi, found := g.repo.Files[name]
35+
if !found {
36+
return source.GitInfo{}
37+
}
38+
return source.NewGitInfo(*gi)
3539
}
3640

3741
func newGitInfo(cfg config.Provider) (*gitInfo, error) {

‎hugolib/hugo_sites.go

+3-4
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@ import (
4141

4242
"github.com/gohugoio/hugo/source"
4343

44-
"github.com/bep/gitmap"
4544
"github.com/gohugoio/hugo/config"
4645

4746
"github.com/gohugoio/hugo/publisher"
@@ -202,13 +201,13 @@ func (h *HugoSites) Data() map[string]any {
202201
return h.data
203202
}
204203

205-
func (h *HugoSites) gitInfoForPage(p page.Page) (*gitmap.GitInfo, error) {
204+
func (h *HugoSites) gitInfoForPage(p page.Page) (source.GitInfo, error) {
206205
if _, err := h.init.gitInfo.Do(); err != nil {
207-
return nil, err
206+
return source.GitInfo{}, err
208207
}
209208

210209
if h.gitInfo == nil {
211-
return nil, nil
210+
return source.GitInfo{}, nil
212211
}
213212

214213
return h.gitInfo.forPage(p), nil

‎hugolib/page.go

+1-3
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,6 @@ import (
3131

3232
"github.com/gohugoio/hugo/hugofs/files"
3333

34-
"github.com/bep/gitmap"
35-
3634
"github.com/gohugoio/hugo/helpers"
3735

3836
"github.com/gohugoio/hugo/common/herrors"
@@ -150,7 +148,7 @@ func (p *pageState) GetIdentity() identity.Identity {
150148
return identity.NewPathIdentity(files.ComponentFolderContent, filepath.FromSlash(p.Pathc()))
151149
}
152150

153-
func (p *pageState) GitInfo() *gitmap.GitInfo {
151+
func (p *pageState) GitInfo() source.GitInfo {
154152
return p.gitInfo
155153
}
156154

‎hugolib/page__common.go

+2-2
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,14 @@ package hugolib
1616
import (
1717
"sync"
1818

19-
"github.com/bep/gitmap"
2019
"github.com/gohugoio/hugo/common/maps"
2120
"github.com/gohugoio/hugo/compare"
2221
"github.com/gohugoio/hugo/lazy"
2322
"github.com/gohugoio/hugo/navigation"
2423
"github.com/gohugoio/hugo/output"
2524
"github.com/gohugoio/hugo/resources/page"
2625
"github.com/gohugoio/hugo/resources/resource"
26+
"github.com/gohugoio/hugo/source"
2727
)
2828

2929
type treeRefProvider interface {
@@ -106,7 +106,7 @@ type pageCommon struct {
106106
shortcodeState *shortcodeHandler
107107

108108
// Set if feature enabled and this is in a Git repo.
109-
gitInfo *gitmap.GitInfo
109+
gitInfo source.GitInfo
110110
codeowners []string
111111

112112
// Positional navigation

‎hugolib/page__meta.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -404,7 +404,7 @@ func (pm *pageMeta) setMetadata(parentBucket *pagesMapBucket, p *pageState, fron
404404
}
405405

406406
var gitAuthorDate time.Time
407-
if p.gitInfo != nil {
407+
if !p.gitInfo.IsZero() {
408408
gitAuthorDate = p.gitInfo.AuthorDate
409409
}
410410

‎hugolib/site.go

+4-4
Original file line numberDiff line numberDiff line change
@@ -110,9 +110,9 @@ type Site struct {
110110

111111
*PageCollections
112112

113-
taxonomies TaxonomyList
113+
taxonomies page.TaxonomyList
114114

115-
Sections Taxonomy
115+
Sections page.Taxonomy
116116
Info *SiteInfo
117117

118118
language *langs.Language
@@ -172,7 +172,7 @@ type Site struct {
172172
init *siteInit
173173
}
174174

175-
func (s *Site) Taxonomies() TaxonomyList {
175+
func (s *Site) Taxonomies() page.TaxonomyList {
176176
s.init.taxonomies.Do()
177177
return s.taxonomies
178178
}
@@ -708,7 +708,7 @@ func (s *SiteInfo) Menus() navigation.Menus {
708708
}
709709

710710
// TODO(bep) type
711-
func (s *SiteInfo) Taxonomies() any {
711+
func (s *SiteInfo) Taxonomies() page.TaxonomyList {
712712
return s.s.Taxonomies()
713713
}
714714

‎langs/language.go

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
1313

14+
// Package langs contains the language related types and function.
1415
package langs
1516

1617
import (

‎markup/converter/hooks/hooks.go

+26
Original file line numberDiff line numberDiff line change
@@ -26,30 +26,56 @@ import (
2626
var _ AttributesOptionsSliceProvider = (*attributes.AttributesHolder)(nil)
2727

2828
type AttributesProvider interface {
29+
// Attributes passed in from Markdown (e.g. { attrName1=attrValue1 attrName2="attr Value 2" }).
2930
Attributes() map[string]any
3031
}
3132

3233
type LinkContext interface {
34+
// The Page being rendered.
3335
Page() any
36+
37+
// The link URL.
3438
Destination() string
39+
40+
// The link title attribute.
3541
Title() string
42+
43+
// The rendered (HTML) text.
3644
Text() hstring.RenderedString
45+
46+
// The plain variant of Text.
3747
PlainText() string
3848
}
3949

4050
type ImageLinkContext interface {
4151
LinkContext
52+
53+
// Returns true if this is a standalone image and the config option
54+
// markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
4255
IsBlock() bool
56+
57+
// Zero-based ordinal for all the images in the current document.
4358
Ordinal() int
4459
}
4560

61+
// CodeblockContext is the context passed to a code block render hook.
4662
type CodeblockContext interface {
4763
AttributesProvider
4864
text.Positioner
65+
66+
// Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.
4967
Options() map[string]any
68+
69+
// The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.
5070
Type() string
71+
72+
// The text between the code fences.
5173
Inner() string
74+
75+
// Zero-based ordinal for all code blocks in the current document.
5276
Ordinal() int
77+
78+
// The owning Page.
5379
Page() any
5480
}
5581

‎markup/highlight/highlight.go

+2
Original file line numberDiff line numberDiff line change
@@ -157,10 +157,12 @@ type HightlightResult struct {
157157
highlighted template.HTML
158158
}
159159

160+
// Wrapped returns the highlighted code wrapped in a <div>, <pre> and <code> tag.
160161
func (h HightlightResult) Wrapped() template.HTML {
161162
return h.highlighted
162163
}
163164

165+
// Inner returns the highlighted code without the wrapping <div>, <pre> and <code> tag, suitable for inline use.
164166
func (h HightlightResult) Inner() template.HTML {
165167
return h.highlighted[h.innerLow:h.innerHigh]
166168
}

‎markup/markup.go

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
1313

14+
// Package markup contains the markup handling (e.g. Markdown).
1415
package markup
1516

1617
import (

‎media/mediaType.go

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
1313

14+
// Package media containes Media Type (MIME type) related types and functions.
1415
package media
1516

1617
import (

‎navigation/menu.go

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2019 The Hugo Authors. All rights reserved.
1+
// Copyright 2023 The Hugo Authors. All rights reserved.
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -11,6 +11,7 @@
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
1313

14+
// Package navigation provides the menu functionality.
1415
package navigation
1516

1617
import (

‎navigation/menu_cache.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
13-
//
13+
1414
package navigation
1515

1616
import (

‎output/outputFormat.go

+2
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// See the License for the specific language governing permissions and
1212
// limitations under the License.
1313

14+
// Package output contains Output Format types and functions.
1415
package output
1516

1617
import (
@@ -400,6 +401,7 @@ func (f Format) BaseFilename() string {
400401
}
401402

402403
// MarshalJSON returns the JSON encoding of f.
404+
// For internal use only.
403405
func (f Format) MarshalJSON() ([]byte, error) {
404406
type Alias Format
405407
return json.Marshal(&struct {

‎resources/docs.go

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Copyright 2023 The Hugo Authors. All rights reserved.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
// http://www.apache.org/licenses/LICENSE-2.0
7+
//
8+
// Unless required by applicable law or agreed to in writing, software
9+
// distributed under the License is distributed on an "AS IS" BASIS,
10+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
// See the License for the specific language governing permissions and
12+
// limitations under the License.
13+
14+
// Package resources contains Resource related types.
15+
package resources

0 commit comments

Comments
 (0)