From c339b6eac0f83c7e58949519a57774913367a6fa Mon Sep 17 00:00:00 2001
From: Eric Firing <efiring@hawaii.edu>
Date: Sun, 21 Jul 2024 09:04:52 -1000
Subject: [PATCH] Handle missing DESCRIPTION in Matlab help

---
 .gitignore                        |  1 +
 gsw/_wrapped_ufuncs.py            | 12 ++++++------
 gsw/tests/test_check_functions.py |  4 ++--
 tools/make_wrapped_ufuncs.py      |  6 ++----
 tools/matlab_parser.py            |  8 +++++++-
 5 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/.gitignore b/.gitignore
index 82f2a18..e869cf6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@
 *.kdev4
 .project
 .pydevproject
+*.orig
 
 # Compiled source #
 ###################
diff --git a/gsw/_wrapped_ufuncs.py b/gsw/_wrapped_ufuncs.py
index 342668f..eefccae 100644
--- a/gsw/_wrapped_ufuncs.py
+++ b/gsw/_wrapped_ufuncs.py
@@ -1157,7 +1157,7 @@ def enthalpy_second_derivatives_CT_exact(SA, CT, p):
 
 def enthalpy_SSO_0(p):
     """
-    Library function; no description.
+    enthalpy at (SSO,CT=0,p)
 
     Parameters
     ----------
@@ -1322,7 +1322,7 @@ def entropy_ice(t, p):
 
 def entropy_part(SA, t, p):
     """
-    Library function; no description.
+    entropy minus the terms that are a function of only SA
 
     Parameters
     ----------
@@ -1344,7 +1344,7 @@ def entropy_part(SA, t, p):
 
 def entropy_part_zerop(SA, pt0):
     """
-    Library function; no description.
+    entropy_part evaluated at the sea surface
 
     Parameters
     ----------
@@ -1761,7 +1761,7 @@ def gibbs_ice_pt0_pt0(pt0):
 
 def gibbs_pt0_pt0(SA, pt0):
     """
-    Library function; no description.
+    gibbs_tt at (SA,pt,0)
 
     Parameters
     ----------
@@ -1894,7 +1894,7 @@ def ice_fraction_to_freeze_seawater(SA, CT, p, t_Ih):
 
 def infunnel(SA, CT, p):
     """
-    Library function; no description.
+    "oceanographic funnel" check for the 75-term equation
 
     Parameters
     ----------
@@ -4327,7 +4327,7 @@ def specvol_second_derivatives_wrt_enthalpy(SA, CT, p):
 
 def specvol_SSO_0(p):
     """
-    Library function; no description.
+    specific volume at (SSO,CT=0,p)
 
     Parameters
     ----------
diff --git a/gsw/tests/test_check_functions.py b/gsw/tests/test_check_functions.py
index 7268fac..f9166c7 100644
--- a/gsw/tests/test_check_functions.py
+++ b/gsw/tests/test_check_functions.py
@@ -14,7 +14,8 @@
 
 # Most of the tests have some nan values, so we need to suppress the warning.
 # Any more careful fix would likely require considerable effort.
-np.seterr(invalid='ignore')
+# We get an overflow from ct_from_enthalpy_exact, but the test passes.
+np.seterr(invalid='ignore', over='ignore')
 
 root_path = os.path.abspath(os.path.dirname(__file__))
 
@@ -28,7 +29,6 @@
              #'melting_ice_into_seawater',  # OK now; fixed nargs mismatch.
              ]
 
-# We get an overflow from ct_from_enthalpy_exact, but the test passes.
 cv = Bunch(np.load(os.path.join(root_path, 'gsw_cv_v3_0.npz')))
 
 # Substitute new check values for the pchip interpolation version.
diff --git a/tools/make_wrapped_ufuncs.py b/tools/make_wrapped_ufuncs.py
index 585f826..0978e02 100644
--- a/tools/make_wrapped_ufuncs.py
+++ b/tools/make_wrapped_ufuncs.py
@@ -25,6 +25,7 @@
 'pt0_cold_ice_poly',
 'pt_from_pot_enthalpy_ice_poly_dh',
 't_freezing_exact',
+'sa_p_inrange',
 }
 
 wrapper_head = '''
@@ -177,11 +178,8 @@ def uf_wrapper(ufname):
                 )
     helpdict = get_helpdict(msig['path'])
 
-    # Filter out minimally documented library functions.
     if 'DESCRIPTION' not in helpdict:
-        print(f"in uf_wrapper, ufname is {ufname}, DESCRIPTION is missing")
-        helpdict['DESCRIPTION'] = ["Library function; no description."]
-        # return None
+        helpdict['DESCRIPTION'] = helpdict["summary"]
 
     try:
         desclist = paragraphs(helpdict['DESCRIPTION'])[0]
diff --git a/tools/matlab_parser.py b/tools/matlab_parser.py
index a49d21a..37b7881 100644
--- a/tools/matlab_parser.py
+++ b/tools/matlab_parser.py
@@ -117,8 +117,14 @@ def help_text_to_dict(help):
     # Headings ('USAGE:', 'DESCRIPTION:', etc.) start with all caps and a colon.
     keypat = r"^([A-Z ]+):(.*)"
     hdict = dict()
+    topline = help[0][2:].strip()
+    parts = topline.split(maxsplit=1)
+    if len(parts) == 2:
+        hdict["summary"] = parts[1:]
+    else:
+        hdict["summary"] = ["no summary"]
     started = False
-    for line in help:
+    for line in help[1:]:
         keyline = re.match(keypat, line)
         if keyline:
             # We found a new heading.