From 2f5d4353ee62e117b4e7c3856f16aaf8760867b3 Mon Sep 17 00:00:00 2001
From: Steven Arcangeli <stevearc@stevearc.com>
Date: Sun, 10 Nov 2024 16:06:43 -0800
Subject: [PATCH] doc: improve type annotations for oil.open_preview

---
 README.md        |  2 +-
 doc/api.md       | 19 ++++++++++---------
 doc/oil.txt      | 12 +++++++-----
 lua/oil/init.lua | 11 +++++++----
 4 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 85b5f01..6bf0282 100644
--- a/README.md
+++ b/README.md
@@ -360,7 +360,7 @@ Note that at the moment the ssh adapter does not support Windows machines, and i
 - [toggle_float(dir)](doc/api.md#toggle_floatdir)
 - [open(dir)](doc/api.md#opendir)
 - [close()](doc/api.md#close)
-- [open_preview(opts)](doc/api.md#open_previewopts)
+- [open_preview(opts, callback)](doc/api.md#open_previewopts-callback)
 - [select(opts, callback)](doc/api.md#selectopts-callback)
 - [save(opts, cb)](doc/api.md#saveopts-cb)
 - [setup(opts)](doc/api.md#setupopts)
diff --git a/doc/api.md b/doc/api.md
index e107293..b1db7cd 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -14,7 +14,7 @@
 - [toggle_float(dir)](#toggle_floatdir)
 - [open(dir)](#opendir)
 - [close()](#close)
-- [open_preview(opts)](#open_previewopts)
+- [open_preview(opts, callback)](#open_previewopts-callback)
 - [select(opts, callback)](#selectopts-callback)
 - [save(opts, cb)](#saveopts-cb)
 - [setup(opts)](#setupopts)
@@ -125,17 +125,18 @@ Open oil browser for a directory
 Restore the buffer that was present when oil was opened
 
 
-## open_preview(opts)
+## open_preview(opts, callback)
 
-`open_preview(opts)` \
+`open_preview(opts, callback)` \
 Preview the entry under the cursor in a split
 
-| Param | Type         | Desc                                               |                                       |
-| ----- | ------------ | -------------------------------------------------- | ------------------------------------- |
-| opts  | `nil\|table` |                                                    |                                       |
-|       | vertical     | `boolean`                                          | Open the buffer in a vertical split   |
-|       | horizontal   | `boolean`                                          | Open the buffer in a horizontal split |
-|       | split        | `"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier                        |
+| Param    | Type                         | Desc                                                    |                                       |
+| -------- | ---------------------------- | ------------------------------------------------------- | ------------------------------------- |
+| opts     | `nil\|oil.OpenPreviewOpts`   |                                                         |                                       |
+|          | vertical                     | `nil\|boolean`                                          | Open the buffer in a vertical split   |
+|          | horizontal                   | `nil\|boolean`                                          | Open the buffer in a horizontal split |
+|          | split                        | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier                        |
+| callback | `nil\|fun(err: nil\|string)` | Called once the preview window has been opened          |                                       |
 
 ## select(opts, callback)
 
diff --git a/doc/oil.txt b/doc/oil.txt
index 03b7bc3..b4ebf1f 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -315,15 +315,17 @@ close()                                                                *oil.clos
     Restore the buffer that was present when oil was opened
 
 
-open_preview({opts})                                            *oil.open_preview*
+open_preview({opts}, {callback})                                *oil.open_preview*
     Preview the entry under the cursor in a split
 
     Parameters:
-      {opts} `nil|table`
-          {vertical}   `boolean` Open the buffer in a vertical split
-          {horizontal} `boolean` Open the buffer in a horizontal split
-          {split}      `"aboveleft"|"belowright"|"topleft"|"botright"` Split
+      {opts}     `nil|oil.OpenPreviewOpts`
+          {vertical}   `nil|boolean` Open the buffer in a vertical split
+          {horizontal} `nil|boolean` Open the buffer in a horizontal split
+          {split}      `nil|"aboveleft"|"belowright"|"topleft"|"botright"` Split
                        modifier
+      {callback} `nil|fun(err: nil|string)` Called once the preview window has
+                 been opened
 
 select({opts}, {callback})                                            *oil.select*
     Select the entry under the cursor
diff --git a/lua/oil/init.lua b/lua/oil/init.lua
index 8c04d8b..600ccc5 100644
--- a/lua/oil/init.lua
+++ b/lua/oil/init.lua
@@ -410,11 +410,14 @@ M.close = function()
   vim.api.nvim_buf_delete(oilbuf, { force = true })
 end
 
+---@class oil.OpenPreviewOpts
+---@field vertical? boolean Open the buffer in a vertical split
+---@field horizontal? boolean Open the buffer in a horizontal split
+---@field split? "aboveleft"|"belowright"|"topleft"|"botright" Split modifier
+
 ---Preview the entry under the cursor in a split
----@param opts nil|table
----    vertical boolean Open the buffer in a vertical split
----    horizontal boolean Open the buffer in a horizontal split
----    split "aboveleft"|"belowright"|"topleft"|"botright" Split modifier
+---@param opts? oil.OpenPreviewOpts
+---@param callback? fun(err: nil|string) Called once the preview window has been opened
 M.open_preview = function(opts, callback)
   opts = opts or {}
   local config = require("oil.config")