Misc doc, code refactoring to improve documentation

10 files changed, 24 insertions, 26 deletions

diff --git a/tpl/diagrams/init.go b/tpl/diagrams/init.go
index 005e942b7..1ed308c57 100644
--- a/tpl/diagrams/init.go
+++ b/tpl/diagrams/init.go
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package diagrams provides template functions for generating diagrams.
 package diagrams
 
 import (
diff --git a/tpl/images/images.go b/tpl/images/images.go
index 1abee1b0c..f4d930570 100644
--- a/tpl/images/images.go
+++ b/tpl/images/images.go
@@ -91,6 +91,7 @@ func (ns *Namespace) Config(path any) (image.Config, error) {
 	return config, nil
 }
 
+// Filter applies the given filters to the image given as the last element in args.
 func (ns *Namespace) Filter(args ...any) (images.ImageResource, error) {
 	if len(args) < 2 {
 		return nil, errors.New("must provide an image and one or more filters")
diff --git a/tpl/openapi/docs.go b/tpl/openapi/docs.go
new file mode 100644
index 000000000..bb7ed9c75
--- /dev/null
+++ b/tpl/openapi/docs.go
@@ -0,0 +1,2 @@
+// Package openapi provides functions for generating OpenAPI (Swagger) documentation.
+package openapi
diff --git a/tpl/openapi/openapi3/openapi3.go b/tpl/openapi/openapi3/openapi3.go
index 9b84e9fbe..31d56289e 100644
--- a/tpl/openapi/openapi3/openapi3.go
+++ b/tpl/openapi/openapi3/openapi3.go
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package openapi3 provides functions for generating OpenAPI v3 (Swagger) documentation.
 package openapi3
 
 import (
@@ -54,6 +55,7 @@ type OpenAPIDocument struct {
 	*kopenapi3.T
 }
 
+// Unmarshal unmarshals the given resource into an OpenAPI 3 document.
 func (ns *Namespace) Unmarshal(r resource.UnmarshableResource) (*OpenAPIDocument, error) {
 	key := r.Key()
 	if key == "" {
diff --git a/tpl/os/os_test.go b/tpl/os/os_test.go
index 98befa061..399adb374 100644
--- a/tpl/os/os_test.go
+++ b/tpl/os/os_test.go
@@ -38,15 +38,15 @@ func TestReadFile(t *testing.T) {
 	}{
 		{filepath.FromSlash("/f/f1.txt"), "f1-content"},
 		{filepath.FromSlash("f/f1.txt"), "f1-content"},
-		{filepath.FromSlash("../f2.txt"), false},
+		{filepath.FromSlash("../f2.txt"), ""},
 		{"", false},
-		{"b", false},
+		{"b", ""},
 	} {
 
 		result, err := ns.ReadFile(test.filename)
 
 		if bb, ok := test.expect.(bool); ok && !bb {
-			b.Assert(err, qt.Not(qt.IsNil))
+			b.Assert(err, qt.Not(qt.IsNil), qt.Commentf("filename: %q", test.filename))
 			continue
 		}
 
diff --git a/tpl/path/path.go b/tpl/path/path.go
index 378b97e03..59add2152 100644
--- a/tpl/path/path.go
+++ b/tpl/path/path.go
@@ -15,11 +15,11 @@
 package path
 
 import (
-	"fmt"
 	_path "path"
 	"path/filepath"
 	"strings"
 
+	"github.com/gohugoio/hugo/common/paths"
 	"github.com/gohugoio/hugo/deps"
 	"github.com/spf13/cast"
 )
@@ -36,17 +36,6 @@ type Namespace struct {
 	deps *deps.Deps
 }
 
-// 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)
-}
-
 // Ext returns the file name extension used by path.
 // The extension is the suffix beginning at the final dot
 // in the final slash-separated element of path;
@@ -117,15 +106,15 @@ func (ns *Namespace) BaseName(path any) (string, error) {
 // The input path is passed into filepath.ToSlash converting any Windows slashes
 // to forward slashes.
 // The returned values have the property that path = dir+file.
-func (ns *Namespace) Split(path any) (DirFile, error) {
+func (ns *Namespace) Split(path any) (paths.DirFile, error) {
 	spath, err := cast.ToStringE(path)
 	if err != nil {
-		return DirFile{}, err
+		return paths.DirFile{}, err
 	}
 	spath = filepath.ToSlash(spath)
 	dir, file := _path.Split(spath)
 
-	return DirFile{Dir: dir, File: file}, nil
+	return paths.DirFile{Dir: dir, File: file}, nil
 }
 
 // Join joins any number of path elements into a single path, adding a
diff --git a/tpl/path/path_test.go b/tpl/path/path_test.go
index 599d8367a..cc49bf28c 100644
--- a/tpl/path/path_test.go
+++ b/tpl/path/path_test.go
@@ -18,6 +18,7 @@ import (
 	"testing"
 
 	qt "github.com/frankban/quicktest"
+	"github.com/gohugoio/hugo/common/paths"
 	"github.com/gohugoio/hugo/config"
 	"github.com/gohugoio/hugo/deps"
 )
@@ -157,7 +158,7 @@ func TestJoin(t *testing.T) {
 			`baz/foo/bar.txt`,
 		},
 		{
-			[]any{"", "baz", DirFile{"big", "john"}, filepath.FromSlash(`foo/bar.txt`)},
+			[]any{"", "baz", paths.DirFile{Dir: "big", File: "john"}, filepath.FromSlash(`foo/bar.txt`)},
 			`baz/big|john/foo/bar.txt`,
 		},
 		{nil, ""},
@@ -186,10 +187,10 @@ func TestSplit(t *testing.T) {
 		path   any
 		expect any
 	}{
-		{filepath.FromSlash(`foo/bar.txt`), DirFile{`foo/`, `bar.txt`}},
-		{filepath.FromSlash(`foo/bar/txt `), DirFile{`foo/bar/`, `txt `}},
-		{`foo.bar.txt`, DirFile{``, `foo.bar.txt`}},
-		{``, DirFile{``, ``}},
+		{filepath.FromSlash(`foo/bar.txt`), paths.DirFile{Dir: `foo/`, File: `bar.txt`}},
+		{filepath.FromSlash(`foo/bar/txt `), paths.DirFile{Dir: `foo/bar/`, File: `txt `}},
+		{`foo.bar.txt`, paths.DirFile{Dir: ``, File: `foo.bar.txt`}},
+		{``, paths.DirFile{Dir: ``, File: ``}},
 		// errors
 		{tstNoStringer{}, false},
 	} {
diff --git a/tpl/resources/resources.go b/tpl/resources/resources.go
index 9d663cb46..85323f057 100644
--- a/tpl/resources/resources.go
+++ b/tpl/resources/resources.go
@@ -414,6 +414,7 @@ func (ns *Namespace) PostCSS(args ...any) (resource.Resource, error) {
 	return ns.postcssClient.Process(r, m)
 }
 
+// PostProcess processes r after the build.
 func (ns *Namespace) PostProcess(r resource.Resource) (postpub.PostPublishedResource, error) {
 	return ns.deps.ResourceSpec.PostProcess(r)
 }
diff --git a/tpl/strings/truncate.go b/tpl/strings/truncate.go
index dd6267280..e8da7b84b 100644
--- a/tpl/strings/truncate.go
+++ b/tpl/strings/truncate.go
@@ -39,9 +39,9 @@ type htmlTag struct {
 	openTag bool
 }
 
-// Truncate truncates a given string to the specified length.
-func (ns *Namespace) Truncate(a any, options ...any) (template.HTML, error) {
-	length, err := cast.ToIntE(a)
+// Truncate truncates the string in s to the specified length.
+func (ns *Namespace) Truncate(s any, options ...any) (template.HTML, error) {
+	length, err := cast.ToIntE(s)
 	if err != nil {
 		return "", err
 	}
diff --git a/tpl/template.go b/tpl/template.go
index 738750de7..dd9249ade 100644
--- a/tpl/template.go
+++ b/tpl/template.go
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package tpl contains template functions and related types.
 package tpl
 
 import (