docs: update

Author: boltlessengineer

doc/rest-nvim-api.txt

@@ -192,21 +192,27 @@ utils.ts_highlight_node({bufnr}, {node}, {ns})
         {ns}     (number)
 
 
-utils.ts_parse_source({source})                          *utils.ts_parse_source*
+utils.ts_get_parser({source})                              *utils.ts_get_parser*
 
     Parameters: ~
         {source}  (string|integer)
 
     Returns: ~
         (vim.treesitter.LanguageTree)
-        (TSTree)
 
 
-utils.ts_find({node}, {type})                                    *utils.ts_find*
+utils.ts_parse_source({source})                          *utils.ts_parse_source*
 
     Parameters: ~
-        {node}  (TSNode)
-        {type}  (string)  @return TSNode?
+        {source}  (string|integer)
+
+    Returns: ~
+        (vim.treesitter.LanguageTree)
+        (TSTree)
+
+
+utils.ts_find()                                                  *utils.ts_find*
+    @return TSNode?
 
 
 utils.ts_upper_node({node})                                *utils.ts_upper_node*

doc/rest-nvim.txt

@@ -5,8 +5,15 @@ rest.nvim                                                            *rest-nvim*
  A fast and asynchronous Neovim HTTP client written in Lua
 
 
+==============================================================================
+Table of Contents                                               *rocks-contents*
+
+rest.nvim ·························································· |rest-nvim|
+rest.nvim commands ········································ |rest-nvim.commands|
+rest.nvim configuration ····································· |rest-nvim.config|
+
 rest.setup({user_configs?})                                         *rest.setup*
-    @deprecated
+    @deprecated use `vim.g.rest_nvim` instead
     Set up rest.nvim
     This api does nothing but set `vim.g.rest_nvim` to `user_configs`
 
@@ -58,15 +65,6 @@ rest.nvim commands                                          *rest-nvim.commands*
  split
 
 
-RestCmd                                                                *RestCmd*
-
-    Fields: ~
-        {impl}  (fun)  The command implementation
-
-
-commands.setup()                                                *commands.setup*
-
-
 ==============================================================================
 rest.nvim configuration                                       *rest-nvim.config*
 
@@ -106,7 +104,10 @@ rest.Opts.Request                                            *rest.Opts.Request*
 rest.Opts.Request.Hooks                                *rest.Opts.Request.Hooks*
 
     Fields: ~
-        {encode_url?}  (boolean)   Encode URL before making request (Default: `true`)
+        {encode_url?}        (boolean)   Encode URL before making request (Default: `true`)
+        {user_agent?}        (string)    Set `User-Agent` header when it is empty. Set as empty string to disable.
+                                         (Default: `rest.nvim {version}`)
+        {set_content_type?}  (boolean)   Set `Content-Type` header when it is empty but request body is provided
 
 
 rest.Opts.Response                                          *rest.Opts.Response*

lua/rest-nvim/autocmds.lua

@@ -1,14 +1,52 @@
 ---@mod rest-nvim.autocmds rest.nvim autocommands
 ---
+---@mod rest-nvim.autocmds rest.nvim autocommands
+---
 ---@brief [[
 ---
---- rest.nvim autocommands
+--- rest.nvim user events
+---
+---rest.nvim provides several |User| |events|.
+---
+---RestRequest or RestRequestPre                   *RestRequest* *RestRequestPre*
+---    Just before executing a request. The request object (with |rest.Request|
+---    type) will be temporarily assigned to the global variable `rest_request`.
+---    Modifing this variable will affect the actual request. Example: >lua
+---
+---    vim.api.nvim_create_autocmd("User", {
+---        pattern = "RestRequestPre",
+---        callback = function()
+---            local req = _G.rest_request
+---            req.headers["user-agent"] = { "myneovim" }
+---        end,
+---    })
+---<
+---
+---RestResponse or RestResponsePre               *RestResponse* *RestResponsePre*
+---    After received the response and all response handlers are executed.
+---    The request and response objects (|rest.Request| and |rest.Response|
+---    types) will be termporarily assigned to the global variabels
+---    `rest_request` and `rest_response`. Modifing this variable won't affect
+---    response handlers but updating cookies and rendering result UI will be
+---    affected. Example: >lua
+---
+---    vim.api.nvim_create_autocmd("User", {
+---        pattern = "RestResponsePre",
+---        callback = function()
+---            local req = _G.rest_request
+---            local res = _G.rest_response
+---            req.url = url_decode(req.url)
+---            res.body = trim_trailing_whitespace(res.body)
+---        end,
+---    })
+---<
 ---
 ---@brief ]]
 
 local autocmds = {}
 
 ---Set up Rest autocommands group
+---@package
 function autocmds.setup()
   vim.api.nvim_create_augroup("Rest", { clear = true })
 

lua/rest-nvim/commands.lua

@@ -37,14 +37,13 @@
 ---                                 copying command to clipboard, directly insert curl
 ---                                 command as a comment.
 ---
---- NOTE: All `:Rest` commands opening new window support |command-modifiers|.
---- For example, you can run `:hor Rest open` to open result pane in horizontal
---- split
+---NOTE: All `:Rest` commands opening new window support |command-modifiers|.
+---For example, you can run `:hor Rest open` to open result pane in horizontal
+---split or run `:tab Rest logs` to open logs file in a new tab.
 ---
 ---@brief ]]
 
--- HACK: what is the type of opts here?
-
+---@package
 ---@class RestCmd
 ---The command implementation
 ---@field impl fun(args:string[], opts: table?)
@@ -269,6 +268,7 @@ local function rest(opts)
   command.impl(args, opts)
 end
 
+---@package
 function commands.setup()
   vim.api.nvim_create_user_command("Rest", rest, {
     nargs = "+",

lua/rest-nvim/init.lua

@@ -6,9 +6,11 @@
 ---
 ---@brief ]]
 
+---@toc rocks-contents
+
 local rest = {}
 
----@deprecated
+---@deprecated use `vim.g.rest_nvim` instead
 ---Set up rest.nvim
 ---This api does nothing but set `vim.g.rest_nvim` to `user_configs`
 ---@param user_configs? rest.Opts User configurations

lua/rest-nvim/request.lua

@@ -26,6 +26,17 @@ local Context = require("rest-nvim.context").Context
 ---@field body? rest.Request.Body
 ---@field handlers fun()[]
 
+---@class rest.Response
+---@field status rest.Response.status Status information from response
+---@field body string? Raw response body
+---@field headers table<string,string[]> Response headers
+---@field statistics table<string,string> Response statistics
+
+---@class rest.Response.status
+---@field code number
+---@field version string
+---@field text string
+
 ---@type rest.Request|nil
 local rest_nvim_last_request = nil
 
@@ -65,9 +76,6 @@ local function run_request(req)
       vim.iter(req.handlers):each(function (f) f(res) end)
       logger.info("handler done")
 
-      -- update cookie jar
-      jar.update_jar(req.url, res)
-
       _G.rest_request = req
       _G.rest_response = res
       vim.api.nvim_exec_autocmds("User", {
@@ -76,6 +84,9 @@ local function run_request(req)
       _G.rest_request = nil
       _G.rest_response = nil
 
+      -- update cookie jar
+      jar.update_jar(req.url, res)
+
       -- update result UI
       ui.update({response = res})
     end)

lua/rest-nvim/response.lua

@@ -79,6 +79,7 @@ local panes = {
           elseif res_type == "octet_stream" then
             body = { "Binary answer" }
           elseif config.response.hooks.format then
+            -- NOTE: format hook runs here because it should be done last.
             body = utils.gq_lines(body, res_type)
           end
         end

lua/rest-nvim/ui/result.lua

@@ -1,3 +1,4 @@
+---@diagnostic disable: invisible
 if vim.fn.has("nvim-0.9.0") ~= 1 then
   vim.notify_once("[rest.nvim] rest.nvim requires at least Neovim >= 0.9 in order to work")
   return