Document the rest of `os2`.

3 files changed, 45 insertions, 5 deletions

diff --git a/core/os/os2/heap.odin b/core/os/os2/heap.odin
index 8f9c7680a..b1db54dc7 100644
--- a/core/os/os2/heap.odin
+++ b/core/os/os2/heap.odin
@@ -2,6 +2,9 @@ package os2
 
 import "base:runtime"
 
+/*
+	Returns the default `heap_allocator` for this specific platform.
+*/
 @(require_results)
 heap_allocator :: proc() -> runtime.Allocator {
 	return runtime.Allocator{
diff --git a/core/os/os2/stat.odin b/core/os/os2/stat.odin
index 338bdffca..f87afc4c9 100644
--- a/core/os/os2/stat.odin
+++ b/core/os/os2/stat.odin
@@ -6,13 +6,16 @@ import "core:time"
 
 Fstat_Callback :: proc(f: ^File, allocator: runtime.Allocator) -> (File_Info, Error)
 
+/*
+	`File_Info` describes a file and is returned from `stat`, `fstat`, and `lstat`.
+*/
 File_Info :: struct {
-	fullpath:          string,
-	name:              string,
+	fullpath:          string,        // fullpath of the file
+	name:              string,        // base name of the file
 
-	inode:             u128, // might be zero if cannot be determined
-	size:              i64 `fmt:"M"`,
-	mode:              Permissions,
+	inode:             u128,          // might be zero if cannot be determined
+	size:              i64 `fmt:"M"`, // length in bytes for regular files; system-dependent for other file types
+	mode:              Permissions,   // file permission flags
 	type:              File_Type,
 
 	creation_time:     time.Time,
@@ -49,6 +52,10 @@ fstat :: proc(f: ^File, allocator: runtime.Allocator) -> (File_Info, Error) {
 	return {}, .Invalid_Callback
 }
 
+/*
+	`stat` returns a `File_Info` describing the named file from the file system.
+	The resulting `File_Info` must be deleted with `file_info_delete`.
+*/
 @(require_results)
 stat :: proc(name: string, allocator: runtime.Allocator) -> (File_Info, Error) {
 	return _stat(name, allocator)
@@ -56,12 +63,21 @@ stat :: proc(name: string, allocator: runtime.Allocator) -> (File_Info, Error) {
 
 lstat :: stat_do_not_follow_links
 
+/*
+	Returns a `File_Info` describing the named file from the file system.
+	If the file is a symbolic link, the `File_Info` returns describes the symbolic link,
+	rather than following the link.
+	The resulting `File_Info` must be deleted with `file_info_delete`.
+*/
 @(require_results)
 stat_do_not_follow_links :: proc(name: string, allocator: runtime.Allocator) -> (File_Info, Error) {
 	return _lstat(name, allocator)
 }
 
 
+/*
+	Returns true if two `File_Info`s are equivalent.
+*/
 @(require_results)
 same_file :: proc(fi1, fi2: File_Info) -> bool {
 	return _same_file(fi1, fi2)
@@ -71,6 +87,10 @@ same_file :: proc(fi1, fi2: File_Info) -> bool {
 last_write_time         :: modification_time
 last_write_time_by_name :: modification_time_by_path
 
+/*
+	Returns the modification time of the file `f`.
+	The resolution of the timestamp is system-dependent.
+*/
 @(require_results)
 modification_time :: proc(f: ^File) -> (time.Time, Error) {
 	temp_allocator := TEMP_ALLOCATOR_GUARD({})
@@ -78,6 +98,10 @@ modification_time :: proc(f: ^File) -> (time.Time, Error) {
 	return fi.modification_time, err
 }
 
+/*
+	Returns the modification time of the named file `path`.
+	The resolution of the timestamp is system-dependent.
+*/
 @(require_results)
 modification_time_by_path :: proc(path: string) -> (time.Time, Error) {
 	temp_allocator := TEMP_ALLOCATOR_GUARD({})
diff --git a/core/os/os2/temp_file.odin b/core/os/os2/temp_file.odin
index 6e7a37788..f0bc3788e 100644
--- a/core/os/os2/temp_file.odin
+++ b/core/os/os2/temp_file.odin
@@ -80,6 +80,19 @@ make_directory_temp :: proc(dir, pattern: string, allocator: runtime.Allocator)
 }
 
 temp_dir :: temp_directory
+
+/*
+	Returns the default directory to use for temporary files.
+
+	On Unix systems, it typically returns $TMPDIR if non-empty, otherwlse `/tmp`.
+	On Windows, it uses `GetTempPathW`, returning the first non-empty value from one of the following:
+	    * `%TMP%`
+	    * `%TEMP%`
+	    * `%USERPROFILE %`
+	    * or the Windows directory
+	  See https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppathw for more information.
+	On wasi, it returns `/tmp`.
+*/
 @(require_results)
 temp_directory :: proc(allocator: runtime.Allocator) -> (string, Error) {
 	return _temp_dir(allocator)