Improve the docstrings of 'output_type' and 'outfile'

Author: seisman

pygmt/src/filter1d.py

@@ -2,6 +2,8 @@
 filter1d - Time domain filtering of 1-D data tables
 """
 
+from typing import Literal
+
 import pandas as pd
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
@@ -20,7 +22,12 @@
     F="filter_type",
     N="time_col",
 )
-def filter1d(data, output_type="pandas", outfile=None, **kwargs):
+def filter1d(
+    data,
+    output_type: Literal["pandas", "numpy", "file"] = "pandas",
+    outfile: str | None = None,
+    **kwargs,
+):
     r"""
     Time domain filtering of 1-D data tables.
 
@@ -38,6 +45,15 @@ def filter1d(data, output_type="pandas", outfile=None, **kwargs):
 
     Parameters
     ----------
+    output_type
+        Desired output type of the result data.
+
+        - ``pandas`` will return a :class:`pandas.DataFrame` object.
+        - ``numpy`` will return a :class:`numpy.ndarray` object.
+        - ``file`` will save the result to the file given by the ``outfile`` parameter.
+    outfile
+        The file name for saving the result. If specified, ``output_type`` will be
+        forced to be ``"file"``.
     filter_type : str
         **type**\ *width*\ [**+h**].
         Set the filter **type**. Choose among convolution and non-convolution
@@ -91,26 +107,14 @@ def filter1d(data, output_type="pandas", outfile=None, **kwargs):
         left-most column is 0, while the right-most is (*n_cols* - 1)
         [Default is ``0``].
 
-    output_type : str
-        Determine the format the xyz data will be returned in [Default is
-        ``pandas``]:
-
-            - ``numpy`` - :class:`numpy.ndarray`
-            - ``pandas``- :class:`pandas.DataFrame`
-            - ``file`` - ASCII file (requires ``outfile``)
-    outfile : str
-        The file name for the output ASCII file.
-
     Returns
     -------
     ret : pandas.DataFrame or numpy.ndarray or None
         Return type depends on ``outfile`` and ``output_type``:
 
-        - None if ``outfile`` is set (output will be stored in file set by
-          ``outfile``)
-        - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is
-          not set (depends on ``output_type`` [Default is
-          :class:`pandas.DataFrame`])
+        - None if ``outfile`` is set (output will be stored in file set by ``outfile``)
+        - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
+          (depends on ``output_type``)
     """
     if kwargs.get("F") is None:
         raise GMTInvalidInput("Pass a required argument to 'filter_type'.")