Figure.text: Improve the documentation to clarify the order of columns in the input files (#2832)

Co-authored-by: Yvonne Fröhlich <[email protected]>

Author: seisman

pygmt/src/text.py

@@ -76,8 +76,21 @@ def text_(  # noqa: PLR0912
     Parameters
     ----------
     textfiles : str or list
-        A text data file name, or a list of file names containing 1 or more
-        records with (x, y[, angle, font, justify], text).
+        A file name or a list of file names containing one or more records.
+        Each record has the following columns:
+
+        * *x*: X coordinate or longitude
+        * *y*: Y coordinate or latitude
+        * *angle*: Angle in degrees counter-clockwise from horizontal
+        * *font*: Text size, font, and color
+        * *justify*: Two-character justification code
+        * *text*: The text string to typeset
+
+        The *angle*, *font*, and *justify* columns are optional and can be set
+        by using the ``angle``, ``font``, and ``justify`` parameters,
+        respectively. If these parameters are set to ``True``, then the
+        corresponding columns must be present in the input file(s) and the
+        columns must be in the order mentioned above.
     x/y : float or 1-D arrays
         The x and y coordinates, or an array of x and y coordinates to plot
         the text.