Misc doc, code refactoring to improve documentation

source/fileInfo.go

@@ -18,7 +18,9 @@ import (
 	"path/filepath"
 	"strings"
 	"sync"
+	"time"
 
+	"github.com/bep/gitmap"
 	"github.com/gohugoio/hugo/common/paths"
 
 	"github.com/gohugoio/hugo/hugofs/files"
@@ -294,3 +296,31 @@ func (sp *SourceSpec) NewFileInfo(fi hugofs.FileMetaInfo) (*FileInfo, error) {
 
 	return f, nil
 }
+
+func NewGitInfo(info gitmap.GitInfo) GitInfo {
+	return GitInfo(info)
+}
+
+// GitInfo provides information about a version controled source file.
+type GitInfo struct {
+	// Commit hash.
+	Hash string `json:"hash"`
+	// Abbreviated commit hash.
+	AbbreviatedHash string `json:"abbreviatedHash"`
+	// The commit message's subject/title line.
+	Subject string `json:"subject"`
+	// The author name, respecting .mailmap.
+	AuthorName string `json:"authorName"`
+	// The author email address, respecting .mailmap.
+	AuthorEmail string `json:"authorEmail"`
+	// The author date.
+	AuthorDate time.Time `json:"authorDate"`
+	// The commit date.
+	CommitDate time.Time `json:"commitDate"`
+}
+
+// IsZero returns true if the GitInfo is empty,
+// meaning it will also be falsy in the Go templates.
+func (g GitInfo) IsZero() bool {
+	return g.Hash == ""
+}

source/sourceSpec.go

@@ -1,4 +1,4 @@
-// Copyright 2017-present 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 source contains the types and functions related to source files.
 package source
 
 import (