add doc comments to path functions

path.go

@@ -8,6 +8,8 @@ import (
 	"strings"
 )
 
+// repoPath returns the absolute path to the sigil repository.
+// It uses SIGIL_REPO environment variable if set, otherwise defaults to ~/.dotfiles.
 func repoPath() (string, error) {
 	if override := os.Getenv("SIGIL_REPO"); override != "" {
 		return filepath.Abs(expandHome(override))
@@ -15,6 +17,8 @@ func repoPath() (string, error) {
 	return filepath.Abs(expandHome("~/.dotfiles"))
 }
 
+// expandHome expands a leading ~ to the user's home directory.
+// Returns the original path unchanged if expansion fails or path doesn't start with ~.
 func expandHome(path string) string {
 	if path == "~" {
 		home, err := os.UserHomeDir()
@@ -33,6 +37,8 @@ func expandHome(path string) string {
 	return path
 }
 
+// compressHome compresses the user's home directory path to ~.
+// Returns the original path if it doesn't start with the home directory.
 func compressHome(path string) string {
 	home, err := os.UserHomeDir()
 	if err != nil {
@@ -50,6 +56,8 @@ func compressHome(path string) string {
 	return path
 }
 
+// splitPackageSpec splits a package spec like "pkg:path/to/file" into (pkg, path).
+// If no colon is present, returns (spec, "", nil).
 func splitPackageSpec(spec string) (string, string, error) {
 	if spec == "" {
 		return "", "", errors.New("missing package")
@@ -72,6 +80,8 @@ func splitPackageSpec(spec string) (string, string, error) {
 	return pkg, rel, nil
 }
 
+// resolvePackageSpec resolves a package spec (name, path, or repo path) to (package, relative path).
+// It handles specs like "pkg:path", absolute paths within the repo, and absolute paths in the target.
 func resolvePackageSpec(spec string) (string, string, error) {
 	repo, err := repoPath()
 	if err != nil {
@@ -100,6 +110,8 @@ func resolvePackageSpec(spec string) (string, string, error) {
 	return splitPackageSpec(spec)
 }
 
+// resolvePathSpec resolves an absolute path spec to a package and relative path.
+// It checks if the path is within the repo or matches a package's target directory.
 func resolvePathSpec(pathSpec, repoAbs string) (string, string, error) {
 	absPath, err := filepath.Abs(pathSpec)
 	if err != nil {
@@ -160,6 +172,8 @@ func resolvePathSpec(pathSpec, repoAbs string) (string, string, error) {
 	return "", "", fmt.Errorf("could not resolve %s to a package", pathSpec)
 }
 
+// findPackageByTarget finds a package name that has the given target root.
+// Returns empty string if no package matches.
 func findPackageByTarget(repo, targetRoot string) (string, error) {
 	repoEntries, err := os.ReadDir(repo)
 	if err != nil {
@@ -201,6 +215,8 @@ func findPackageByTarget(repo, targetRoot string) (string, error) {
 	return "", nil
 }
 
+// repoPathForTarget returns the repo file path that a target symlink points to.
+// Returns empty string if the target is not a symlink to the repo.
 func repoPathForTarget(targetPath, repo string) (string, error) {
 	info, err := os.Lstat(targetPath)
 	if err != nil {