Add tests and improve docstrings

Author: seisman

pygmt/params/position.py

@@ -17,10 +17,40 @@ class Position(BaseParam):
     The class for positioning GMT embellishments.
     """
 
-    location: str | tuple[float | str, float | str]
+    #: Specify the reference point on the plot. The method of defining the reference
+    #: point is controlled by ``type``, and the exact location is set by ``position``.
+    location: Sequence[float | str] | AnchorCode
+
+    #: Specify the type of coordinates used to define the reference point. It can be
+    #: one of the following values:
+    #:
+    #: - ``"mapcoords"``: ``position`` is specified as (*longitude*, *latitude*) in map
+    #:   coordinates.
+    #: - ``"boxcoords"``: ``position`` is specified as (*nx*, *ny*) in normalized
+    #:   coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
+    #: - ``"plotcoords"``: ``position`` is specified as (*x*, *y*) in plot coordinates,
+    #:   i.e., distances from the lower-left plot origin given in inches, centimeters,
+    #:   or points.
+    #: - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
+    #:   :doc:`two-character justification codes </techref/justification_codes>`,
+    #:   indicating a specific location relative to the plot bounding box.
+    #:
     type: Literal["mapcoords", "inside", "outside", "boxcoords", "plotcoords"]
-    anchor: AnchorCode
-    offset: Sequence[float | str]
+
+    #: Specify the anchor point of the GMT logo, using one of the
+    #: :doc:`2-character justification codes </techref/justification_codes>`. The
+    #: default value depends on ``position_type``.
+    #:
+    #: - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.
+    #: - ``position_type="outside"``: ``anchor`` defaults to the mirror opposite of
+    #:   ``position``.
+    #: - Otherwise, ``anchor`` defaults to ``"MC"`` (middle center).
+    anchor: AnchorCode | None = None
+
+    #: Specifies an offset for the anchor point as *offset* or (*offset_x*, *offset_y*).
+    #: If a single value *offset* is given, both *offset_x* and *offset_y* are set to
+    #: *offset*.
+    offset: Sequence[float | str] | None = None
 
     @property
     def _aliases(self):
@@ -37,6 +67,6 @@ def _aliases(self):
                 },
             ),
             Alias(self.location, name="location", sep="/", size=2),
-            Alias(self.anchor, name="anchor"),
-            Alias(self.offset, name="offset", sep="/", size=2),
+            Alias(self.anchor, name="anchor", prefix="+j"),
+            Alias(self.offset, name="offset", prefix="+o", sep="/", size=2),
         ]

pygmt/tests/test_params_position.py

@@ -0,0 +1,30 @@
+"""
+Test the Position class.
+"""
+
+from pygmt.params import Position
+
+
+def test_params_position_types():
+    """
+    Test the Position class with different types of coordinate systems.
+    """
+    assert str(Position(location=(10, 20), type="mapcoords")) == "g10/20"
+    assert str(Position(location=(0.1, 0.2), type="boxcoords")) == "n0.1/0.2"
+    assert str(Position(location=("5c", "3c"), type="plotcoords")) == "x5c/3c"
+    assert str(Position(location="TL", type="inside")) == "jTL"
+    assert str(Position(location="BR", type="outside")) == "JBR"
+
+
+def test_params_position_anchor_offset():
+    """
+    Test the Position class with anchor and offset parameters.
+    """
+    pos = Position(location=(10, 20), type="mapcoords", anchor="TL")
+    assert str(pos) == "g10/20+jTL"
+
+    pos = Position(location=(10, 20), type="mapcoords", offset=(1, 2))
+    assert str(pos) == "g10/20+o1/2"
+
+    pos = Position(location="TL", type="inside", anchor="MC", offset=("1c", "2c"))
+    assert str(pos) == "jTL+jMC+o1c/2c"