docs: update help pages, readme

README.md

@@ -192,13 +192,19 @@ local default_config = {
 Create a new http file or open an existing one and run the <kbd>:Rest run {name}</kbd> command, or
 just place the cursor over the request and simply run <kbd>:Rest run</kbd>.
 
+### HTTP file syntax
+
+```
+Method Request-URI HTTP-Version
+Header-field: Header-value
+
+Request-Body
+```
+
 > [!NOTE]
->
-> 1. You can find examples of use in the [spec/examples](./spec/examples) directory.
->
-> 2. `rest.nvim` supports multiple HTTP requests in one file. It selects the
->    request in the current cursor line, no matters the position as long as
->    the cursor is on a request tree-sitter node.
+> rest.nvim follows [intellij's http client spec](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)
+> for `.http` file syntax. You can find examples of use in the [spec/examples](./spec/examples)
+> directory.
 
 ### Keybindings
 

doc/rest-nvim-api.txt

@@ -109,7 +109,7 @@ parser.eval_context({source}, {ctx}, {endline})
         {endline}  (number)        zero-based line number
 
 
-parser.get_cursor_request_node()                *parser.get_cursor_request_node*
+parser.get_request_node_by_cursor()          *parser.get_request_node_by_cursor*
     @return TSNode? node TSNode with type `section`
 
 
@@ -162,6 +162,12 @@ parser.get_request_names({source})                    *parser.get_request_names*
         (string[])
 
 
+parser.get_request_node({name})                        *parser.get_request_node*
+
+    Parameters: ~
+        {name}  (string|nil)  @return TSNode?
+
+
 parser.parse({node}, {source}, {ctx?})                            *parser.parse*
     Parse the request node and create Request object. Returns `nil` if parsing
     failed.
@@ -286,12 +292,13 @@ utils.parse_http_time()                                  *utils.parse_http_time*
 
 
                                                        *utils.ts_highlight_node*
-utils.ts_highlight_node({bufnr}, {node}, {ns})
+utils.ts_highlight_node({bufnr}, {node}, {ns}, {timeout})
 
     Parameters: ~
-        {bufnr}  (number)
-        {node}   (TSNode)
-        {ns}     (number)
+        {bufnr}    (number)
+        {node}     (TSNode)
+        {ns}       (number)
+        {timeout}  (number)
 
 
 utils.ts_get_parser({source})                              *utils.ts_get_parser*

doc/rest-nvim.txt

@@ -164,7 +164,7 @@ rest.Opts.Response.Hooks                              *rest.Opts.Response.Hooks*
 
     Fields: ~
         {decode_url?}  (boolean)   Decode url segments on response UI too improve readability (Default: `true`)
-        {format?}      (boolean)   Format the response body (Default: `true`)
+        {format?}      (boolean)   Format the response body with |'formatexpr'| or |'formatprg'| (Default: `true`)
 
 
 rest.Opts.Clients                                            *rest.Opts.Clients*

lua/rest-nvim/config/init.lua

@@ -51,7 +51,7 @@ local config
 ---@class rest.Opts.Response.Hooks
 --- Decode url segments on response UI too improve readability (Default: `true`)
 ---@field decode_url? boolean
---- Format the response body (Default: `true`)
+--- Format the response body with |'formatexpr'| or |'formatprg'| (Default: `true`)
 ---@field format? boolean
 
 ---@class rest.Opts.Clients