From 3a0e52008a9e976fd9a4e5ab21b864091e93e177 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Rodr=C3=ADguez?= <deivid.rodriguez@riseup.net>
Date: Fri, 25 Mar 2022 10:19:30 +0100
Subject: [PATCH] Improve `sort_link` documentation (#1290)

The signature of this method is quite convoluted, I tried to clarify it.
---
 CHANGELOG.md |  2 ++
 README.md    | 16 ++++++++++++----
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf9dbcce..367bf139 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Improve `sort_link` documentation.
+
 * Deprecate passing two trailing hashes to `sort_link`, for example:
 
   ```ruby
diff --git a/README.md b/README.md
index aec7290c..836e70a1 100644
--- a/README.md
+++ b/README.md
@@ -146,8 +146,11 @@ The `search_form_for` answer format can be set like this:
 ```erb
 <%= sort_link(@q, :name) %>
 ```
-Additional options can be passed after the column attribute, like a different
-column title or a default sort order:
+Additional options can be passed after the column parameter, like a different
+column title or a default sort order.
+
+If the first option after the column parameter is a String, it's considered a
+custom label for the link:
 
 ```erb
 <%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
@@ -169,7 +172,8 @@ explicitly to avoid an `uninitialized constant Model::Xxxable` error (see issue
 <%= sort_link(@q, :xxxable_of_Ymodel_type_some_attribute, 'Attribute Name') %>
 ```
 
-You can also sort on multiple fields by specifying an ordered array:
+If the first option after the column parameter and/or the label parameter is an
+Array, it will be used for sorting on multiple fields:
 
 ```erb
 <%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
@@ -179,7 +183,8 @@ In the example above, clicking the link will sort by `last_name` and then
 `first_name`. Specifying the sort direction on a field in the array tells
 Ransack to _always_ sort that particular field in the specified direction.
 
-Multiple `default_order` fields may also be specified with a hash:
+Multiple `default_order` fields may also be specified with a trailing options
+Hash:
 
 ```erb
 <%= sort_link(@q, :last_name, %i(last_name first_name),
@@ -208,6 +213,9 @@ and you can then sort by this virtual field:
 <%= sort_link(@q, :reverse_name) %>
 ```
 
+The trailing options Hash can also be used for passing additional options to the
+generated link, like `class:`.
+
 The sort link order indicator arrows may be globally customized by setting a
 `custom_arrows` option in an initializer file like
 `config/initializers/ransack.rb`.