Misc doc, code refactoring to improve documentation

4 files changed, 16 insertions, 0 deletions

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
 }