Updates

Author: seisman

doc/api/index.rst

@@ -206,6 +206,15 @@ Miscellaneous
     print_clib_info
     show_versions
 
+Common Parameters
+-----------------
+
+.. autosummary::
+    :toctree: generated
+
+    params.Box
+
+
 .. currentmodule:: pygmt
 
 Datasets

pygmt/params/base.py

@@ -1,3 +1,6 @@
+"""
+General class for PyGMT parameters.
+"""
 from __future__ import annotations
 
 from typing import NamedTuple
@@ -6,23 +9,29 @@
 
 
 class Alias(NamedTuple):
+    """
+    Alias PyGMT long-form parameter to GMT single-letter option flag.
+    """
+
     name: str
     modifier: str
     separator: str | None = None
 
 
 class BaseParams:
     """
+    Base class for PyGMT parameters.
+
     Examples
     --------
     >>> import dataclasses
     >>> from pygmt.params.base import BaseParams
     >>>
     >>> @dataclasses.dataclass(repr=False)
     ... class Test(BaseParams):
-    ...     attr1 : Any = None
-    ...     attr2 : Any = None
-    ...     attr3 : Any = None
+    ...     attr1: Any = None
+    ...     attr2: Any = None
+    ...     attr3: Any = None
     ...
     ...     __aliases__ = [
     ...         Alias("attr1", ""),
@@ -35,20 +44,27 @@ class BaseParams:
     >>> repr(var)
     "Test(attr1='val1')"
     """
+
     def __str__(self):
+        """
+        String representation of the object that can be passed to GMT directly.
+        """
         values = []
         for alias in self.__aliases__:
             value = getattr(self, alias.name)
             if value in (None, False):
                 continue
-            if value is True:
+            elif value is True:
                 value = ""
-            if is_nonstr_iter(value):
+            elif is_nonstr_iter(value):
                 value = alias.separator.join(map(str, value))
             values.append(f"{alias.modifier}{value}")
         return "".join(values)
 
     def __repr__(self):
+        """
+        String representation of the object.
+        """
         string = []
         for alias in self.__aliases__:
             value = getattr(self, alias.name)

pygmt/params/box.py

@@ -11,6 +11,23 @@
 
 @dataclass(repr=False)
 class Box(BaseParams):
+    """
+    Class for the box around GMT embellishments.
+
+    Attributes
+    ----------
+    clearance
+        Set clearances between the embellishment and the box border. Can be either a
+        scalar value or a list of two/four values.
+
+        - a scalar value means a uniform clearance in all four directions.
+        - a list of two values means separate clearances in x- and y- directions.
+        - a list of four values means separate clearances for left/right/bottom/top.
+    fill
+        Fill for the box. None means no fill.
+
+    """
+
     clearance: float | str | Sequence[float | str] | None = None
     fill: str | None = None
     innerborder: str | Sequence | None = None