hare

commit c6ca6e4c9ce56bb1866db6c3f758d1351f540124
parent 217a1b3451b8e70b12c083d4e34e04c0c1b6dc48
Author: Drew DeVault <sir@cmpwn.com>
Date:   Sat,  8 Jan 2022 15:02:19 +0100

dirs: improve documentation of 'prog' parameter

Signed-off-by: Drew DeVault <sir@cmpwn.com>

Diffstat:
M
dirs/xdg.ha
 | 
29
++++++++++++++---------------

1 file changed, 14 insertions(+), 15 deletions(-)
diff --git a/dirs/xdg.ha b/dirs/xdg.ha
@@ -27,29 +27,28 @@ fn lookup(prog: str, var: str, default: str) str = {
 	return path;
 };
 
-// Returns a directory suitable for storing config files. If 'prog' is given, a
-// unique path for this program to store data will be returned. The return value
-// is statically allocated and will be overwritten on subsequent calls to any
+// Returns a directory suitable for storing config files. The "prog" parameter
+// should be a descriptive name unique to this program. The return value is
+// statically allocated and will be overwritten on subsequent calls to any
 // function in the dirs module.
 export fn config(prog: str) str = lookup(prog, "XDG_CONFIG_HOME", ".config");
 
-// Returns an [[fs::fs]] for storing config files. If 'prog' is given, a unique
-// path for this program to store data will be returned.
+// Returns an [[fs::fs]] for storing config files. The "prog" parameter
+// should be a descriptive name unique to this program.
 export fn configfs(prog: str) *fs::fs = os::diropen(config(prog)) as *fs::fs;
 
-// Returns a directory suitable for cache files. If 'prog' is given, a unique
-// path for this program to store data will be returned. The return value is
-// statically allocated and will be overwritten on subsequent calls to any
-// function in the dirs module.
+// Returns a directory suitable for cache files. The "prog" parameter should be
+// a descriptive name unique to this program. The return value is statically
+// allocated and will be overwritten on subsequent calls to any function in the
+// dirs module.
 export fn cache(prog: str) str = lookup(prog, "XDG_CACHE_HOME", ".cache");
 
-// Returns an [[fs::fs]] for cache files. If 'prog' is given, a unique path for
-// this program to store data will be returned.
+// Returns an [[fs::fs]] for cache files.
 export fn cachefs(prog: str) *fs::fs = os::diropen(cache(prog)) as *fs::fs;
 
-// Returns a directory suitable for persistent data files. If 'prog' is given, a
-// unique path for this program to store data will be returned. The return value
-// is statically allocated and will be overwritten on subsequent calls to any
+// Returns a directory suitable for persistent data files. The "prog" parameter
+// should be a descriptive name unique to this program. The return value is
+// statically allocated and will be overwritten on subsequent calls to any
 // function in the dirs module.
 export fn data(prog: str) str = {
 	static let buf = path::buffer { ... };
@@ -57,6 +56,6 @@ export fn data(prog: str) str = {
 	return lookup(prog, "XDG_DATA_HOME", fragment);
 };
 
-// Returns an [[fs::fs]] for persistent data files. If 'prog' is given, a unique
+// Returns an [[fs::fs]] for persistent data files. If "prog" is given, a unique
 // path for this program to store data will be returned.
 export fn datafs(prog: str) *fs::fs = os::diropen(data(prog)) as *fs::fs;