Update documentation for os2 once more!

core/os/os2/file_util.odin

@@ -4,10 +4,18 @@ import "base:runtime"
 import "core:strconv"
 import "core:unicode/utf8"
 
+/*
+	`write_string` writes a string `s` to file `f`.
+	Returns the number of bytes written and an error, if any is encountered.
+*/
 write_string :: proc(f: ^File, s: string) -> (n: int, err: Error) {
 	return write(f, transmute([]byte)s)
 }
 
+/*
+	`write_strings` writes a variadic list of strings `strings` to file `f`.
+	Returns the number of bytes written and an error, if any is encountered.
+*/
 write_strings :: proc(f: ^File, strings: ..string) -> (n: int, err: Error) {
 	for s in strings {
 		m: int
@@ -19,11 +27,18 @@ write_strings :: proc(f: ^File, strings: ..string) -> (n: int, err: Error) {
 	}
 	return
 }
-
+/*
+	`write_byte` writes a byte `b` to file `f`.
+	Returns the number of bytes written and an error, if any is encountered.
+*/
 write_byte :: proc(f: ^File, b: byte) -> (n: int, err: Error) {
 	return write(f, []byte{b})
 }
 
+/*
+	`write_rune` writes a rune `r` as an UTF-8 encoded string to file `f`.
+	Returns the number of bytes written and an error, if any is encountered.
+*/
 write_rune :: proc(f: ^File, r: rune) -> (n: int, err: Error) {
 	if r < utf8.RUNE_SELF {
 		return write_byte(f, byte(r))
@@ -34,6 +49,10 @@ write_rune :: proc(f: ^File, r: rune) -> (n: int, err: Error) {
 	return write(f, b[:n])
 }
 
+/*
+	`write_encoded_rune` writes a rune `r` as an UTF-8 encoded string which with escaped control codes to file `f`.
+	Returns the number of bytes written and an error, if any is encountered.
+*/
 write_encoded_rune :: proc(f: ^File, r: rune) -> (n: int, err: Error) {
 	wrap :: proc(m: int, merr: Error, n: ^int, err: ^Error) -> bool {
 		n^ += m
@@ -73,6 +92,31 @@ write_encoded_rune :: proc(f: ^File, r: rune) -> (n: int, err: Error) {
 	return
 }
 
+/*
+	`write_ptr` is a utility procedure that writes the bytes points at `data` with length `len`.
+
+	It is equivalent to: `write(f, ([^]byte)(data)[:len])`
+*/
+write_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {
+	return write(f, ([^]byte)(data)[:len])
+}
+
+/*
+	`read_ptr` is a utility procedure that reads the bytes points at `data` with length `len`.
+
+	It is equivalent to: `read(f, ([^]byte)(data)[:len])`
+*/
+read_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {
+	return read(f, ([^]byte)(data)[:len])
+}
+
+
+
+/*
+	`read_at_least` reads from `f` into `buf` until it has read at least `min` bytes.
+	It returns the number of bytes copied and an error if fewer bytes were read.
+	The error is only an `io.EOF` if no bytes were read.
+*/
 read_at_least :: proc(f: ^File, buf: []byte, min: int) -> (n: int, err: Error) {
 	if len(buf) < min {
 		return 0, .Short_Buffer
@@ -88,17 +132,17 @@ read_at_least :: proc(f: ^File, buf: []byte, min: int) -> (n: int, err: Error) {
 	return
 }
 
+/*
+	`read_full` reads exactly `len(buf)` bytes from `f` into `buf`.
+	It returns the number of bytes copied and an error if fewer bytes were read.
+	The error is only an `io.EOF` if no bytes were read.
+
+	It is equivalent to `read_at_least(f, buf, len(buf))`.
+*/
 read_full :: proc(f: ^File, buf: []byte) -> (n: int, err: Error) {
 	return read_at_least(f, buf, len(buf))
 }
 
-write_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {
-	return write(f, ([^]byte)(data)[:len])
-}
-
-read_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {
-	return read(f, ([^]byte)(data)[:len])
-}
 
 
 read_entire_file :: proc{
@@ -106,6 +150,10 @@ read_entire_file :: proc{
 	read_entire_file_from_file,
 }
 
+/*
+	`read_entire_file_from_path` reads the entire named file `name` into memory allocated with `allocator`.
+	A slice of bytes and an error is returned, if any error is encountered.
+*/
 @(require_results)
 read_entire_file_from_path :: proc(name: string, allocator: runtime.Allocator, loc := #caller_location) -> (data: []byte, err: Error) {
 	f := open(name) or_return
@@ -113,6 +161,10 @@ read_entire_file_from_path :: proc(name: string, allocator: runtime.Allocator, l
 	return read_entire_file_from_file(f, allocator, loc)
 }
 
+/*
+	`read_entire_file_from_file` reads the entire file `f` into memory allocated with `allocator`.
+	A slice of bytes and an error is returned, if any error is encountered.
+*/
 @(require_results)
 read_entire_file_from_file :: proc(f: ^File, allocator: runtime.Allocator, loc := #caller_location) -> (data: []byte, err: Error) {
 	size: int
@@ -160,8 +212,23 @@ read_entire_file_from_file :: proc(f: ^File, allocator: runtime.Allocator, loc :
 	}
 }
 
+/*
+	`write_entire_file` writes the contents of `data` into named file `name`.
+	It defaults with the permssions `perm := Permissions_Read_All + {.Write_User}`, and `truncate`s by default.
+	An error is returned if any is encountered.
+*/
+write_entire_file :: proc{
+	write_entire_file_from_bytes,
+	write_entire_file_from_string,
+}
+
+/*
+	`write_entire_file_from_bytes` writes the contents of `data` into named file `name`.
+	It defaults with the permssions `perm := Permissions_Read_All + {.Write_User}`, and `truncate`s by default.
+	An error is returned if any is encountered.
+*/
 @(require_results)
-write_entire_file :: proc(name: string, data: []byte, perm := Permissions_Read_All + {.Write_User}, truncate := true) -> Error {
+write_entire_file_from_bytes :: proc(name: string, data: []byte, perm := Permissions_Read_All + {.Write_User}, truncate := true) -> Error {
 	flags := O_WRONLY|O_CREATE
 	if truncate {
 		flags |= O_TRUNC
@@ -174,3 +241,14 @@ write_entire_file :: proc(name: string, data: []byte, perm := Permissions_Read_A
 	return err
 }
 
+
+
+/*
+	`write_entire_file_from_string` writes the contents of `data` into named file `name`.
+	It defaults with the permssions `perm := Permissions_Read_All + {.Write_User}`, and `truncate`s by default.
+	An error is returned if any is encountered.
+*/
+@(require_results)
+write_entire_file_from_string :: proc(name: string, data: string, perm := Permissions_Read_All + {.Write_User}, truncate := true) -> Error {
+	return write_entire_file(name, transmute([]byte)data, perm, truncate)
+}