Improve the docstrings for perspective

Author: seisman

pygmt/helpers/decorators.py

@@ -262,12 +262,24 @@
         pen : str
             Set pen attributes for lines or the outline of symbols.""",
     "perspective": r"""
-        perspective : list or str
-            [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\
-            [**+w**\ *lon0*/*lat0*\[/*z0*]][**+v**\ *x0*/*y0*].
-            Select perspective view and set the azimuth and elevation angle of
-            the viewpoint [Default is ``[180, 90]``]. Full documentation is at
-            :gmt-docs:`gmt.html#perspective-full`.""",
+        perspective
+            Select perspective view and set the azimuth and elevation of the viewpoint.
+
+            It can be specified as *azimuth*, (*azimuth*, *elevation*), or
+            (*azimuth*, *elevation*, *zlevel*), in which,
+
+            - *azimuth*: Azimuth angle of the viewpoint in degrees [Default is 180,
+              i.e., looking from south to north].
+            - *elevation*: Elevation angle of the viewpoint above the horizon [Default
+              is 90, i.e., looking straight down].
+            - *zlevel*: Z-level at which 2-D elements (e.g., the map frame) are drawn.
+              Only applies when used together with ``zsize``/``zscale``. [Default is at
+              the bottom of the z-axis].
+
+            Alternatively, set ``perspective=True`` to use the perspective setting used
+            in the previous plotting method. Or passing a string with the full GMT
+            syntax to have more control. See :gmt-docs:`gmt.html#perspective-full` for
+            details.""",
     "projection": r"""
         projection
             *projcode*\[*projparams*/]\ *width*\|\ *scale*.