From d3a365c950be31a0d46920ce4ff6f23e78939b67 Mon Sep 17 00:00:00 2001
From: Steven Arcangeli <stevearc@stevearc.com>
Date: Sun, 2 Jun 2024 17:45:22 -0700
Subject: [PATCH] doc: improve documentation for set_sort (#401)

---
 doc/api.md       | 11 ++++++++---
 doc/oil.txt      |  7 ++++++-
 lua/oil/init.lua |  4 +++-
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/doc/api.md b/doc/api.md
index 40503f8..77a07da 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -59,9 +59,14 @@ Change the display columns for oil
 `set_sort(sort)` \
 Change the sort order for oil
 
-| Param | Type       | Desc |
-| ----- | ---------- | ---- |
-| sort  | `string[]` | []   |
+| Param | Type             | Desc                                                                                  |
+| ----- | ---------------- | ------------------------------------------------------------------------------------- |
+| sort  | `oil.SortSpec[]` | List of columns plus direction. See :help oil-columns to see which ones are sortable. |
+
+**Examples:**
+```lua
+require("oil").set_sort({ { "type", "asc" }, { "size", "desc" } })
+```
 
 ## set_is_hidden_file(is_hidden_file)
 
diff --git a/doc/oil.txt b/doc/oil.txt
index b8ba7bf..11043ff 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -255,7 +255,12 @@ set_sort({sort})                                                    *oil.set_sor
     Change the sort order for oil
 
     Parameters:
-      {sort} `string[]` []
+      {sort} `oil.SortSpec[]` List of columns plus direction. See :help oil-
+             columns to see which ones are sortable.
+
+    Examples: >lua
+      require("oil").set_sort({ { "type", "asc" }, { "size", "desc" } })
+<
 
 set_is_hidden_file({is_hidden_file})                      *oil.set_is_hidden_file*
     Change how oil determines if the file is hidden
diff --git a/lua/oil/init.lua b/lua/oil/init.lua
index 8e7fe10..f025085 100644
--- a/lua/oil/init.lua
+++ b/lua/oil/init.lua
@@ -121,7 +121,9 @@ M.set_columns = function(cols)
 end
 
 ---Change the sort order for oil
----@param sort string[][]
+---@param sort oil.SortSpec[] List of columns plus direction. See :help oil-columns to see which ones are sortable.
+---@example
+--- require("oil").set_sort({ { "type", "asc" }, { "size", "desc" } })
 M.set_sort = function(sort)
   require("oil.view").set_sort(sort)
 end