Figure.coast: Migrate the borders parameter to the new alias system and improve docstrings (#4257)

Author: seisman

pygmt/src/coast.py

@@ -20,9 +20,7 @@
 
 
 @fmt_docstring
-@use_alias(
-    A="area_thresh", C="lakes", E="dcw", L="map_scale", N="borders", W="shorelines"
-)
+@use_alias(A="area_thresh", C="lakes", E="dcw", L="map_scale", W="shorelines")
 def coast(  # noqa: PLR0913
     self,
     resolution: Literal[
@@ -31,6 +29,7 @@ def coast(  # noqa: PLR0913
     land: str | None = None,
     water: str | None = None,
     rivers: int | str | Sequence[int | str] | None = None,
+    borders: int | str | Sequence[int | str] | None = None,
     box: Box | bool = False,
     projection: str | None = None,
     frame: str | Sequence[str] | bool = False,
@@ -144,19 +143,26 @@ def coast(  # noqa: PLR0913
         rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
         appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
         and other box properties.
-    borders : int, str, or list
-        *border*\ [/*pen*].
-        Draw political boundaries. Specify the type of boundary and
-        [optionally] append pen attributes [Default is ``"0.25p,black,solid"``].
+    borders
+        Draw political boundaries. Specify the type of boundary to draw, and optionally
+        append a pen attribute, in the format *border*\ /*pen* [Default pen is
+        ``"0.25p,black,solid"``]. Pass a sequence of border types or *border*\ /*pen*
+        strings to draw different border types with different pens.
+
+        Choose from the following border types:
 
-        Choose from the list of boundaries below. Pass a list to ``borders`` to
-        use multiple arguments.
+        - ``1``: National boundaries
+        - ``2``: State boundaries within the Americas
+        - ``3``: Marine boundaries
+        - ``"a"``: All boundaries (types ``1`` - ``3``)
 
-        - ``1``: national boundaries
-        - ``2``: state boundaries within the Americas
-        - ``3``: marine boundaries
-        - ``"a"``: all boundaries (``1`` - ``3``)
+        Example usage:
 
+        - ``borders=1``: Draw national boundaries with default pen.
+        - ``borders="1/0.5p,red"``: Draw national boundaries with a 0.5-point red pen.
+        - ``borders=["1/0.5p,red", "2/0.3p,blue,dashed"]``: Draw national boundaries
+          with a 0.5-point red pen and state boundaries with a 0.3-point dashed blue
+          pen.
     shorelines : bool, int, str, or list
         [*level*\ /]\ *pen*.
         Draw shorelines [Default is no shorelines]. Append pen attributes
@@ -212,11 +218,12 @@ def coast(  # noqa: PLR0913
         kwargs.get("G", land) is None
         and kwargs.get("S", water) is None
         and kwargs.get("I", rivers) is None
-        and not args_in_kwargs(args=["C", "N", "E", "Q", "W"], kwargs=kwargs)
+        and kwargs.get("N", borders) is None
+        and not args_in_kwargs(args=["C", "E", "Q", "W"], kwargs=kwargs)
     ):
         msg = (
             "At least one of the following parameters must be specified: "
-            "land, water, rivers, lakes, borders, dcw, Q, or shorelines."
+            "land, water, rivers, borders, lakes, dcw, Q, or shorelines."
         )
         raise GMTInvalidInput(msg)
 
@@ -236,6 +243,7 @@ def coast(  # noqa: PLR0913
         F=Alias(box, name="box"),
         G=Alias(land, name="land"),
         I=Alias(rivers, name="rivers"),
+        N=Alias(borders, name="borders"),
         S=Alias(water, name="water"),
     ).add_common(
         B=frame,