Merge pull request #1594 from sogaiu/tweak-docstrings

Tweak docstrings for better handling

Author: bakpakin

src/boot/boot.janet

@@ -1933,7 +1933,7 @@
     that will match any value without creating a binding.
 
   While a symbol pattern will ordinarily match any value, the pattern `(@ <sym>)`,
-  where <sym> is any symbol, will attempt to match `x` against a value
+  where `<sym>` is any symbol, will attempt to match `x` against a value
   already bound to `<sym>`, rather than matching and rebinding it.
 
   Any other value pattern will only match if it is equal to `x`.
@@ -2574,7 +2574,7 @@
     * `:env` -- the environment to compile against - default is the current env
 
     * `:source` -- source path for better errors (use keywords for non-paths) - default
-      is :<anonymous>
+      is `:<anonymous>`
 
     * `:on-compile-error` -- callback when compilation fails - default is bad-compile
 
@@ -4483,8 +4483,10 @@
       (errorf "bad path %s - file is a %s" src mode)))
 
   (defn bundle/add-bin
-    `Shorthand for adding scripts during an install. Scripts will be installed to
-    (string (dyn *syspath*) "/bin") by default and will be set to be executable.`
+    ``
+    Shorthand for adding scripts during an install. Scripts will be installed to
+    `(string (dyn *syspath*) "/bin")` by default and will be set to be executable.
+    ``
     [manifest src &opt dest chmod-mode]
     (def s (sep))
     (default dest (last (string/split s src)))

src/core/filewatch.c

@@ -599,33 +599,33 @@ JANET_CORE_FN(cfun_filewatch_make,
 JANET_CORE_FN(cfun_filewatch_add,
               "(filewatch/add watcher path &opt flags)",
               "Add a path to the watcher. Available flags depend on the current OS, and are as follows:\n\n"
-              "Windows/MINGW (flags correspond to FILE_NOTIFY_CHANGE_* flags in win32 documentation):\n\n"
+              "Windows/MINGW (flags correspond to `FILE_NOTIFY_CHANGE_*` flags in win32 documentation):\n\n"
               "* `:all` - trigger an event for all of the below triggers.\n\n"
-              "* `:attributes` - FILE_NOTIFY_CHANGE_ATTRIBUTES\n\n"
-              "* `:creation` - FILE_NOTIFY_CHANGE_CREATION\n\n"
-              "* `:dir-name` - FILE_NOTIFY_CHANGE_DIR_NAME\n\n"
-              "* `:last-access` - FILE_NOTIFY_CHANGE_LAST_ACCESS\n\n"
-              "* `:last-write` - FILE_NOTIFY_CHANGE_LAST_WRITE\n\n"
-              "* `:security` - FILE_NOTIFY_CHANGE_SECURITY\n\n"
-              "* `:size` - FILE_NOTIFY_CHANGE_SIZE\n\n"
+              "* `:attributes` - `FILE_NOTIFY_CHANGE_ATTRIBUTES`\n\n"
+              "* `:creation` - `FILE_NOTIFY_CHANGE_CREATION`\n\n"
+              "* `:dir-name` - `FILE_NOTIFY_CHANGE_DIR_NAME`\n\n"
+              "* `:last-access` - `FILE_NOTIFY_CHANGE_LAST_ACCESS`\n\n"
+              "* `:last-write` - `FILE_NOTIFY_CHANGE_LAST_WRITE`\n\n"
+              "* `:security` - `FILE_NOTIFY_CHANGE_SECURITY`\n\n"
+              "* `:size` - `FILE_NOTIFY_CHANGE_SIZE`\n\n"
               "* `:recursive` - watch subdirectories recursively\n\n"
-              "Linux (flags correspond to IN_* flags from <sys/inotify.h>):\n\n"
-              "* `:access` - IN_ACCESS\n\n"
-              "* `:all` - IN_ALL_EVENTS\n\n"
-              "* `:attrib` - IN_ATTRIB\n\n"
-              "* `:close-nowrite` - IN_CLOSE_NOWRITE\n\n"
-              "* `:close-write` - IN_CLOSE_WRITE\n\n"
-              "* `:create` - IN_CREATE\n\n"
-              "* `:delete` - IN_DELETE\n\n"
-              "* `:delete-self` - IN_DELETE_SELF\n\n"
-              "* `:ignored` - IN_IGNORED\n\n"
-              "* `:modify` - IN_MODIFY\n\n"
-              "* `:move-self` - IN_MOVE_SELF\n\n"
-              "* `:moved-from` - IN_MOVED_FROM\n\n"
-              "* `:moved-to` - IN_MOVED_TO\n\n"
-              "* `:open` - IN_OPEN\n\n"
-              "* `:q-overflow` - IN_Q_OVERFLOW\n\n"
-              "* `:unmount` - IN_UNMOUNT\n\n\n"
+              "Linux (flags correspond to `IN_*` flags from <sys/inotify.h>):\n\n"
+              "* `:access` - `IN_ACCESS`\n\n"
+              "* `:all` - `IN_ALL_EVENTS`\n\n"
+              "* `:attrib` - `IN_ATTRIB`\n\n"
+              "* `:close-nowrite` - `IN_CLOSE_NOWRITE`\n\n"
+              "* `:close-write` - `IN_CLOSE_WRITE`\n\n"
+              "* `:create` - `IN_CREATE`\n\n"
+              "* `:delete` - `IN_DELETE`\n\n"
+              "* `:delete-self` - `IN_DELETE_SELF`\n\n"
+              "* `:ignored` - `IN_IGNORED`\n\n"
+              "* `:modify` - `IN_MODIFY`\n\n"
+              "* `:move-self` - `IN_MOVE_SELF`\n\n"
+              "* `:moved-from` - `IN_MOVED_FROM`\n\n"
+              "* `:moved-to` - `IN_MOVED_TO`\n\n"
+              "* `:open` - `IN_OPEN`\n\n"
+              "* `:q-overflow` - `IN_Q_OVERFLOW`\n\n"
+              "* `:unmount` - `IN_UNMOUNT`\n\n\n"
               "On Windows, events will have the following possible types:\n\n"
               "* `:unknown`\n\n"
               "* `:added`\n\n"

src/core/net.c

@@ -657,7 +657,7 @@ JANET_CORE_FN(cfun_net_listen,
               "The type parameter specifies the type of network connection, either "
               "a :stream (usually tcp), or :datagram (usually udp). If not specified, the default is "
               ":stream. The host and port arguments are the same as in net/address. The last boolean parameter `no-reuse` will "
-              "disable the use of SO_REUSEADDR and SO_REUSEPORT when creating a server on some operating systems.") {
+              "disable the use of `SO_REUSEADDR` and `SO_REUSEPORT` when creating a server on some operating systems.") {
     janet_sandbox_assert(JANET_SANDBOX_NET_LISTEN);
     janet_arity(argc, 2, 4);