Add assumptions for resolveWindows, resolvePosixand realpath

* doc: `realpath` does not work for `file/..`.
* doc: `resolveWindows`, `resolvePosix` do not work with relative paths

lib/std/fs/path.zig

@@ -484,6 +484,7 @@ pub fn resolve(allocator: Allocator, paths: []const []const u8) ![]u8 {
 /// Path separators are canonicalized to '\\' and drives are canonicalized to capital letters.
 /// Note: all usage of this function should be audited due to the existence of symlinks.
 /// Without performing actual syscalls, resolving `..` could be incorrect.
+/// assume: paths describes network path (prefix `\\`) or root path (prefix `X:` or `x:`)
 pub fn resolveWindows(allocator: Allocator, paths: []const []const u8) ![]u8 {
     if (paths.len == 0) {
         assert(native_os == .windows); // resolveWindows called on non windows can't use getCwd
@@ -670,6 +671,7 @@ pub fn resolveWindows(allocator: Allocator, paths: []const []const u8) ![]u8 {
 /// If all paths are relative it uses the current working directory as a starting point.
 /// Note: all usage of this function should be audited due to the existence of symlinks.
 /// Without performing actual syscalls, resolving `..` could be incorrect.
+/// assume: paths describes absolute path (prefixed by `/`)
 pub fn resolvePosix(allocator: Allocator, paths: []const []const u8) ![]u8 {
     if (paths.len == 0) {
         assert(native_os != .windows); // resolvePosix called on windows can't use getCwd

lib/std/os.zig

@@ -5091,6 +5091,9 @@ pub const RealPathError = error{
 /// extra `/` characters in `pathname`.
 /// The return value is a slice of `out_buffer`, but not necessarily from the beginning.
 /// See also `realpathZ` and `realpathW`.
+/// assume: `/` followed by file description can be `cd`ed to.
+/// Hence, `file/..` can not be used. Use `fs.path.resolve` and `fs.path.relative`.
+/// assume: if relative path used, then they are relative to getcwd()
 pub fn realpath(pathname: []const u8, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8 {
     if (builtin.os.tag == .windows) {
         const pathname_w = try windows.sliceToPrefixedFileW(pathname);