From 4d1006e804b6a4bd22a0a8400d4622f72821098a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?=
 <94163266+yvonnefroehlich@users.noreply.github.com>
Date: Fri, 18 Nov 2022 13:40:39 +0100
Subject: [PATCH] Figure.text: Deprecate parameter "incols" to "use_word"
 (remove in v0.10.0)  (#1964)

* Rename 'incols' to 'use_word'
* Replace -i placeholder with -it docstring
* Add 'deprecate_parameter' for two minor releases
* Remove 'i' or 'it' from 'kwargs_to_strings'
* Adjust docstring corresponding to 'use_word=<integer>'

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
---
 pygmt/src/text.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/pygmt/src/text.py b/pygmt/src/text.py
index 779d678c01b..dcdae152a6b 100644
--- a/pygmt/src/text.py
+++ b/pygmt/src/text.py
@@ -7,6 +7,7 @@
 from pygmt.helpers import (
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -15,6 +16,7 @@
 
 
 @fmt_docstring
+@deprecate_parameter("incols", "use_word", "v0.8.0", remove_version="v0.10.0")
 @use_alias(
     R="region",
     J="projection",
@@ -33,7 +35,7 @@
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
+    it="use_word",
     p="perspective",
     t="transparency",
     w="wrap",
@@ -45,7 +47,6 @@
     font="sequence_comma",
     justify="sequence_comma",
     c="sequence_comma",
-    i="sequence_comma",
     p="sequence",
 )
 def text_(
@@ -156,7 +157,10 @@ def text_(
     {find}
     {coltypes}
     {header}
-    {incols}
+    use_word : int
+        Select a specific word from the trailing text, with the first
+        word being 0 [Default is the entire trailing text]. No numerical
+        columns can be specified.
     {perspective}
     {transparency}
         ``transparency`` can also be a 1d array to set varying