From a69d84dd25bb74215924b72ba251906c54e78fb5 Mon Sep 17 00:00:00 2001
From: Ade Attwood <adrian.attwood@marketdojo.com>
Date: Wed, 1 Mar 2023 21:22:54 +0000
Subject: [PATCH] docs: update the API section of the docs

---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1449b73..99f0ee8 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,41 @@ Action can be run on selected candidates provide functionality
 
 ## API
 
+### ivy.run
+
+The `ivy.run` function is the core function in the plugin, it will launch the
+completion window and display the items from your items function. When the
+users accept one of the candidates with an [action](#actions), it will call the
+callback function to in most cases open the item in the desired location.
+
+```lua
+  ---@param name string
+  ---@param items fun(input: string): { content: string }[] | string
+  ---@param callback fun(result: string, action: string)
+  vim.ivy.run = function(name, items, callback) end
+```
+
+#### Name `string`
+
+The name is the display name for the command and will be the name of the buffer
+in the completion window
+
+#### Items `fun(input: string): { content: string }[] | string`
+
+The items function is a function that will return the candidates to display in
+the completion window. This can return a string where each line will be a
+completion item. Or an array of tables where the `content` will be the
+completion item.
+
+#### Callback `fun(result: string, action: string)`
+
+The function that will run when the user selects a completion item. Generally
+this will open the item in the desired location. For example, in the file
+finder with will open the file in a new buffer. If the user selects the
+vertical split action it will open the buffer in a new `vsplit`
+
+#### Example
+
 ```lua
   vim.ivy.run(
     -- The name given to the results window and displayed to the user
@@ -78,7 +113,30 @@ Action can be run on selected candidates provide functionality
     -- Call back function to get all the candidates that will be displayed in
     -- the results window, The `input` will be passed in, so you can filter
     -- your results with the value from the prompt
-    function(input) return { "One", "Two", Three } end,
+    function(input)
+  vim.ivy.run(
+    -- The name given to the results window and displayed to the user
+    "Title",
+    -- Call back function to get all the candidates that will be displayed in
+    -- the results window, The `input` will be passed in, so you can filter
+    -- your results with the value from the prompt
+    function(input)
+      return {
+        { content = "One" },
+        { content = "Two" },
+        { content = "Three" },
+      }
+    end,
+    -- Action callback that will be called on the completion or peek actions.
+    -- The currently selected item is passed in as the result.
+    function(result) vim.cmd("edit " .. result) end
+  )
+      return {
+        { content = "One" },
+        { content = "Two" },
+        { content = "Three" },
+      }
+    end,
     -- Action callback that will be called on the completion or peek actions.
     -- The currently selected item is passed in as the result.
     function(result) vim.cmd("edit " .. result) end