Figure.basemap/Figure.coast: Recommend to use the Figure.scalebar method to add a scalebar

pygmt/src/basemap.py

@@ -11,20 +11,15 @@
 
 
 @fmt_docstring
-@use_alias(
-    L="map_scale",
-    F="box",
-    Td="rose",
-    Tm="compass",
-    f="coltypes",
-)
-def basemap(
+@use_alias(F="box", Td="rose", Tm="compass", f="coltypes")
+def basemap(  # noqa: PLR0913
     self,
     projection: str | None = None,
     zsize: float | str | None = None,
     zscale: float | str | None = None,
     frame: str | Sequence[str] | bool = False,
     region: Sequence[float | str] | str | None = None,
+    map_scale: str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
@@ -35,13 +30,17 @@ def basemap(
     r"""
     Plot base maps and frames.
 
-    Creates a basic or fancy basemap with axes, fill, and titles. Several
-    map projections are available, and the user may specify separate
-    tick-mark intervals for boundary annotation, ticking, and [optionally]
-    gridlines. A simple map scale or directional rose may also be plotted.
+    Creates a basic or fancy basemap with axes, fill, and titles. Several map
+    projections are available, and the user may specify separate tick-mark intervals for
+    boundary annotation, ticking, and [optionally] gridlines.
 
-    At least one of the parameters ``frame``, ``map_scale``, ``rose``, or
-    ``compass`` must be specified if not in subplot mode.
+    At least one of the parameters ``frame``, ``map_scale``, ``rose``, or ``compass``
+    must be specified if not in subplot mode.
+
+    See also the following methods that provide higher-level interfaces to the GMT's
+    ``basemap`` module:
+
+    - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot.
 
     Full GMT docs at :gmt-docs:`basemap.html`.
 
@@ -50,6 +49,7 @@ def basemap(
        - J = projection
        - Jz = zscale
        - JZ = zsize
+       - L = map_scale
        - R = region
        - V = verbose
        - c = panel
@@ -64,10 +64,15 @@ def basemap(
     $region
         *Required if this is the first plot command.*
     $frame
-    map_scale : str
-        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
-        **+w**\ *length*.
-        Draw a simple map scale centered on the reference point specified.
+    map_scale
+        Draw a map scale bar on the plot.
+
+        .. deprecated:: v0.19.0
+
+            This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead,
+            which provides a more comprehensive and flexible API for adding scale bars
+            to plots. This parameter still accepts raw GMT CLI strings for the ``-L``
+            option of the ``basemap`` module for backward compatibility.
     box : bool or str
         [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
         [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
@@ -103,6 +108,7 @@ def basemap(
     aliasdict = AliasSystem(
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
+        L=Alias(map_scale, name="map_scale"),  # Deprecated.
     ).add_common(
         B=frame,
         J=projection,

pygmt/src/coast.py

@@ -15,7 +15,7 @@
 
 
 @fmt_docstring
-@use_alias(A="area_thresh", C="lakes", E="dcw", L="map_scale")
+@use_alias(A="area_thresh", C="lakes", E="dcw")
 def coast(  # noqa: PLR0913
     self,
     resolution: Literal[
@@ -26,6 +26,7 @@ def coast(  # noqa: PLR0913
     rivers: int | str | Sequence[int | str] | None = None,
     borders: int | str | Sequence[int | str] | None = None,
     shorelines: bool | str | Sequence[int | str] = False,
+    map_scale: str | None = None,
     box: Box | bool = False,
     projection: str | None = None,
     frame: str | Sequence[str] | bool = False,
@@ -63,6 +64,7 @@ def coast(  # noqa: PLR0913
        - G = land
        - I = rivers
        - J = projection
+       - L = map_scale
        - R = region
        - S = water
        - V = verbose
@@ -131,9 +133,15 @@ def coast(  # noqa: PLR0913
         - ``rivers=["1/0.5p,blue", "5/0.3p,cyan,dashed"]``: Draw permanent major rivers
           with a 0.5-point blue pen and intermittent major rivers with a 0.3-point
           dashed cyan pen.
-    map_scale : str
-        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*.
-        Draw a simple map scale centered on the reference point specified.
+    map_scale
+        Draw a map scale bar on the plot.
+
+        .. deprecated:: v0.19.0
+
+            This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead,
+            which provides a more comprehensive and flexible API for adding scale bars
+            to plots. This parameter still accepts raw GMT CLI strings for the ``-L``
+            option of the ``basemap`` module for backward compatibility.
     box
         Draw a background box behind the map scale or rose. If set to ``True``, a simple
         rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
@@ -256,6 +264,7 @@ def coast(  # noqa: PLR0913
         F=Alias(box, name="box"),
         G=Alias(land, name="land"),
         I=Alias(rivers, name="rivers"),
+        L=Alias(map_scale, name="map_scale"),  # Deprecated.
         N=Alias(borders, name="borders"),
         S=Alias(water, name="water"),
         W=Alias(shorelines, name="shorelines"),