doc/guide: update content and sample code (#3408)

- Add `Makefile` for example codes. (cherry-pick from old uvbook repo)
- Add a new example "Default loop" to "Basics of libuv"/"Default loop"
- Document review and update: `Introduction`, `Basics of libuv`, `Filesystem`
    + Update the referenced libuv code snippet
    + Link update: http->https
    **Content Updates**:
    - `filesystem.rst`#L291-L297: Add note for `uv_fs_event_start`
    - `filesystem.rst`#L334: Add description of the callback function parameter `status`

The following examples have been tested manually in WSL2 (Ubuntu 20.04) with libuv 1.42.0:
- helloworld
- default-loop
- idle-basic
- uvcat
- uvtee
- onchange (test on macOS)

Co-authored-by: Nikhil Marathe <nsm.nikhil@gmail.com>

1 files changed, 20 insertions, 10 deletions

diff --git a/docs/src/guide/filesystem.rst b/docs/src/guide/filesystem.rst
index 2d5f6cb9..c0bfbf5b 100644
--- a/docs/src/guide/filesystem.rst
+++ b/docs/src/guide/filesystem.rst
@@ -13,7 +13,7 @@ Simple filesystem read/write is achieved using the ``uv_fs_*`` functions and the
     watchers registered with the event loop when application interaction is
     required.
 
-.. _thread pool: http://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling
+.. _thread pool: https://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling
 
 All filesystem functions have two forms - *synchronous* and *asynchronous*.
 
@@ -66,7 +66,7 @@ The ``result`` field of a ``uv_fs_t`` is the file descriptor in case of the
 .. literalinclude:: ../../code/uvcat/main.c
     :language: c
     :linenos:
-    :lines: 26-40
+    :lines: 26-39
     :emphasize-lines: 2,8,12
 
 In the case of a read call, you should pass an *initialized* buffer which will
@@ -91,7 +91,7 @@ callbacks.
 .. literalinclude:: ../../code/uvcat/main.c
     :language: c
     :linenos:
-    :lines: 16-24
+    :lines: 17-24
     :emphasize-lines: 6
 
 .. warning::
@@ -132,6 +132,7 @@ same patterns as the read/write/open calls, returning the result in the
     int uv_fs_copyfile(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
     int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
     int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb);
+    int uv_fs_mkstemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb);
     int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
     int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb);
     int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent);
@@ -149,6 +150,7 @@ same patterns as the read/write/open calls, returning the result in the
     int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
     int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb);
     int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb);
+    int uv_fs_lutime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb);
     int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
     int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb);
     int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
@@ -158,6 +160,7 @@ same patterns as the read/write/open calls, returning the result in the
     int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
     int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
     int uv_fs_lchown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
+    int uv_fs_statfs(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
 
 
 .. _buffers-and-streams:
@@ -190,7 +193,7 @@ and freed by the application.
 
 .. ERROR::
 
-    THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER**
+    **THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER**
 
 To demonstrate streams we will need to use ``uv_pipe_t``. This allows streaming
 local files [#]_. Here is a simple tee utility using libuv.  Doing all operations
@@ -209,7 +212,7 @@ opened as bidirectional by default.
 .. literalinclude:: ../../code/uvtee/main.c
     :language: c
     :linenos:
-    :lines: 61-80
+    :lines: 62-80
     :emphasize-lines: 4,5,15
 
 The third argument of ``uv_pipe_init()`` should be set to 1 for IPC using named
@@ -285,6 +288,13 @@ a command whenever any of the watched files change::
 
     ./onchange <command> <file1> [file2] ...
 
+.. note::
+
+    Currently this example only works on OSX and Windows.
+    Refer to the `notes of uv_fs_event_start`_ function.
+
+.. _notes of uv_fs_event_start: https://docs.libuv.org/en/v1.x/fs_event.html#c.uv_fs_event_start
+
 The file change notification is started using ``uv_fs_event_init()``:
 
 .. rubric:: onchange/main.c - The setup
@@ -300,8 +310,8 @@ argument, ``flags``, can be:
 .. code-block:: c
 
     /*
-    * Flags to be passed to uv_fs_event_start().
-    */
+     * Flags to be passed to uv_fs_event_start().
+     */
     enum uv_fs_event_flags {
         UV_FS_EVENT_WATCH_ENTRY = 1,
         UV_FS_EVENT_STAT = 2,
@@ -319,9 +329,9 @@ The callback will receive the following arguments:
   #. ``const char *filename`` - If a directory is being monitored, this is the
      file which was changed. Only non-``null`` on Linux and Windows. May be ``null``
      even on those platforms.
-  #. ``int flags`` - one of ``UV_RENAME`` or ``UV_CHANGE``, or a bitwise OR of
-       both.
-  #. ``int status`` - Currently 0.
+  #. ``int events`` - one of ``UV_RENAME`` or ``UV_CHANGE``, or a bitwise OR of
+     both.
+  #. ``int status`` - If ``status < 0``, there is an :ref:`libuv error<libuv-error-handling>`.
 
 In our example we simply print the arguments and run the command using
 ``system()``.