From 49d1c1c5124c914ffaf4632d4a30a9dbd0d202f7 Mon Sep 17 00:00:00 2001
From: Santiago Soler <santisoler@fastmail.com>
Date: Fri, 8 Sep 2023 11:54:31 -0700
Subject: [PATCH] Improve docstrings of prism gravity functions (#429)

Add new fields to prism layer gravity method. Replace mgal for mGal in
all docstrings and comments.
---
 harmonica/_forward/prism.py           | 4 ++--
 harmonica/_forward/prism_layer.py     | 8 ++++++--
 harmonica/_forward/tesseroid.py       | 4 ++--
 harmonica/tests/test_point_gravity.py | 8 ++++----
 4 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/harmonica/_forward/prism.py b/harmonica/_forward/prism.py
index 3e8a2603a..7281205f9 100644
--- a/harmonica/_forward/prism.py
+++ b/harmonica/_forward/prism.py
@@ -80,7 +80,7 @@ def prism_gravity(
 
         - The gravitational potential is returned in
           :math:`\text{J}/\text{kg}`.
-        - The gravity acceleration components are returned in mgal
+        - The gravity acceleration components are returned in mGal
           (:math:`\text{m}/\text{s}^2`).
         - The tensor components are returned in Eotvos (:math:`\text{s}^{-2}`).
 
@@ -133,7 +133,7 @@ def prism_gravity(
     result : array
         Gravitational field generated by the prisms on the computation points.
         Gravitational potential is returned in :math:`\text{J}/\text{kg}`,
-        acceleration components in mgal, and tensor components in Eotvos.
+        acceleration components in mGal, and tensor components in Eotvos.
 
     Notes
     -----
diff --git a/harmonica/_forward/prism_layer.py b/harmonica/_forward/prism_layer.py
index faee124cc..26322ca9a 100644
--- a/harmonica/_forward/prism_layer.py
+++ b/harmonica/_forward/prism_layer.py
@@ -337,7 +337,11 @@ def gravity(
             Gravitational field that wants to be computed.
             The available fields are:
             - Gravitational potential: ``potential``
+            - Eastward acceleration: ``g_e``
+            - Northward acceleration: ``g_n``
             - Downward acceleration: ``g_z``
+            - Diagonal tensor components: ``g_ee``, ``g_nn``, ``g_zz``
+            - Non-diagonal tensor components: ``g_en``, ``g_ez``, ``g_nz``
         density_name : str (optional)
             Name of the property layer (or ``data_var`` of the
             :class:`xarray.Dataset`) that will be used for the density of each
@@ -350,8 +354,8 @@ def gravity(
         Returns
         -------
         result : array
-            Gravitational field generated by the prisms on the computation
-            points in mGal.
+            Gravitational potential is returned in :math:`\text{J}/\text{kg}`,
+            acceleration components in mGal, and tensor components in Eotvos.
 
         See also
         --------
diff --git a/harmonica/_forward/tesseroid.py b/harmonica/_forward/tesseroid.py
index 3472695c9..481faa32d 100644
--- a/harmonica/_forward/tesseroid.py
+++ b/harmonica/_forward/tesseroid.py
@@ -55,7 +55,7 @@ def tesseroid_gravity(
 
         - The gravitational potential is returned in
           :math:`\text{J}/\text{kg}`.
-        - The gravity acceleration components are returned in mgal
+        - The gravity acceleration components are returned in mGal
           (:math:`\text{m}/\text{s}^2`).
 
     Parameters
@@ -110,7 +110,7 @@ def tesseroid_gravity(
     result : array
         Gravitational field generated by the tesseroids on the computation
         points. Gravitational potential is returned in
-        :math:`\text{J}/\text{kg}` and acceleration components in mgal.
+        :math:`\text{J}/\text{kg}` and acceleration components in mGal.
 
     References
     ----------
diff --git a/harmonica/tests/test_point_gravity.py b/harmonica/tests/test_point_gravity.py
index 9f710daea..88a31cb25 100644
--- a/harmonica/tests/test_point_gravity.py
+++ b/harmonica/tests/test_point_gravity.py
@@ -628,7 +628,7 @@ def test_point_mass_on_origin():
     longitude = np.linspace(-180, 180, 37)
     latitude = np.linspace(-90, 90, 19)
     longitude, latitude, radius = np.meshgrid(longitude, latitude, radius)
-    # Analytical solutions (accelerations are in mgal and tensor components in
+    # Analytical solutions (accelerations are in mGal and tensor components in
     # eotvos)
     analytical = {
         "potential": GRAVITATIONAL_CONST * mass / radius,
@@ -662,7 +662,7 @@ def test_point_mass_same_radial_direction(field):
                     np.array(height + sphere_radius),
                 ]
                 # Analytical solutions
-                # (accelerations are in mgal and tensor components in eotvos)
+                # (accelerations are in mGal and tensor components in eotvos)
                 analytical = {
                     "potential": GRAVITATIONAL_CONST * mass / height,
                     "g_z": GRAVITATIONAL_CONST * mass / height**2 * 1e5,
@@ -690,7 +690,7 @@ def test_point_mass_potential_on_equator():
                     np.array(radius),
                 ]
                 # Analytical solutions
-                # (accelerations are in mgal and tensor components in eotvos)
+                # (accelerations are in mGal and tensor components in eotvos)
                 distance = (
                     2 * radius * np.sin(0.5 * np.radians(abs(longitude - longitude_p)))
                 )
@@ -720,7 +720,7 @@ def test_point_mass_potential_on_same_meridian():
                     np.array(radius),
                 ]
                 # Analytical solutions
-                # (accelerations are in mgal and tensor components in eotvos)
+                # (accelerations are in mGal and tensor components in eotvos)
                 distance = (
                     2 * radius * np.sin(0.5 * np.radians(abs(latitude - latitude_p)))
                 )