doc: add warning about uv_close

docs/src/fs.rst

@@ -190,9 +190,13 @@ Public members
 
 .. c:member:: ssize_t uv_fs_t.result
 
-    Result of the request. < 0 means error, success otherwise. On requests such
-    as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of
-    data that was read or written, respectively.
+    Result of the request. < 0 means error, success otherwise. This field is always set, regardless
+    of the request being sync or async.
+
+    For synchronous calls, the result of each operation is this field.
+
+    Check each function's documentation to check if the field has
+    an extended meaning.
 
 .. c:member:: uv_stat_t uv_fs_t.statbuf
 
@@ -211,8 +215,10 @@ API
 
 .. c:function:: void uv_fs_req_cleanup(uv_fs_t* req)
 
-    Cleanup request. Must be called after a request is finished to deallocate
-    any memory libuv might have allocated.
+    Cleanup request. Must be called after a request is finished to cleanup
+    any resources libuv might have allocated.
+
+    It must be called for all requests, regardless of success or failure.
 
 .. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
 
@@ -222,6 +228,17 @@ API
 
     Equivalent to :man:`open(2)`.
 
+    The `req->result` field contains the opened file descriptor, of < 0 for error.
+
+    The `flags` argument has different semantics depending on the OS:
+
+        - On Unix, they are directly passed to :man:`open(2)`.
+        - On Windows, the following flags are implemented, emulating Unix semantics: `UV_FS_O_APPEND`,
+          `UV_FS_O_CREAT`, `UV_FS_O_EXCL`, `UV_FS_O_FILEMAP`, `UV_FS_O_RANDOM`, `UV_FS_O_RDONLY`,
+          `UV_FS_O_RDWR`, `UV_FS_O_SEQUENTIAL`, `UV_FS_O_SHORT_LIVED`, `UV_FS_O_TEMPORARY`,
+          `UV_FS_O_TRUNC`, `UV_FS_O_WRONLY`, `UV_FS_O_DIRECT`, `UV_FS_O_DSYNC`, `UV_FS_O_EXLOCK`,
+          `UV_FS_O_SYNC`.
+
     .. note::
         On Windows libuv uses `CreateFileW` and thus the file is always opened
         in binary mode. Because of this the O_BINARY and O_TEXT flags are not
@@ -232,6 +249,8 @@ API
     Equivalent to :man:`preadv(2)`. If the `offset` argument is `-1`, then
     the current file offset is used and updated.
 
+    The result in `req->result` indicates the amount of bytes read, if > 0.
+
     .. warning::
         On Windows, under non-MSVC environments (e.g. when GCC or Clang is used
         to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal
@@ -246,6 +265,8 @@ API
     Equivalent to :man:`pwritev(2)`. If the `offset` argument is `-1`, then
     the current file offset is used and updated.
 
+    The result in `req->result` indicates the amount of bytes written, if > 0.
+
     .. warning::
         On Windows, under non-MSVC environments (e.g. when GCC or Clang is used
         to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal

docs/src/handle.rst

@@ -156,6 +156,10 @@ API
     `close_cb` can be `NULL` in cases where no cleanup or deallocation is
     necessary.
 
+    .. warning::
+        Calling this function multiple times is not supported and will produce
+        a crash.
+
 .. c:function:: void uv_ref(uv_handle_t* handle)
 
     Reference the given handle. References are idempotent, that is, if a handle

docs/src/threading.rst

@@ -133,19 +133,26 @@ Threads
 .. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2)
 
 .. c:function:: int uv_thread_setpriority(uv_thread_t tid, int priority)
+
     If the function succeeds, the return value is 0.
     If the function fails, the return value is less than zero.
+
     Sets the scheduling priority of the thread specified by tid. It requires elevated
     privilege to set specific priorities on some platforms.
-    The priority can be set to the following constants. UV_THREAD_PRIORITY_HIGHEST, 
-    UV_THREAD_PRIORITY_ABOVE_NORMAL, UV_THREAD_PRIORITY_NORMAL, 
-    UV_THREAD_PRIORITY_BELOW_NORMAL, UV_THREAD_PRIORITY_LOWEST.
+
+    The priority can be set to the following constants: `UV_THREAD_PRIORITY_HIGHEST`, 
+    `UV_THREAD_PRIORITY_ABOVE_NORMAL`, `UV_THREAD_PRIORITY_NORMAL`,
+    `UV_THREAD_PRIORITY_BELOW_NORMAL`, `UV_THREAD_PRIORITY_LOWEST`.
+
 .. c:function:: int uv_thread_getpriority(uv_thread_t tid, int* priority)
+
     If the function succeeds, the return value is 0.
     If the function fails, the return value is less than zero.
+
     Retrieves the scheduling priority of the thread specified by tid. The value in the
     output parameter priority is platform dependent.
-    For Linux, when schedule policy is SCHED_OTHER (default), priority is 0.
+
+    For Linux, when schedule policy is `SCHED_OTHER` (default), priority is 0.
 
 Thread-local storage
 ^^^^^^^^^^^^^^^^^^^^