DOC: datetime-feedback: Various comment/documentation tweaks from Chuck's review feedback

4 files changed, 23 insertions, 18 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 49c0811bd..270147ae2 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -6032,8 +6032,8 @@ add_newdoc('numpy.core.multiarray', 'is_busday',
     Returns
     -------
     out : array of bool
-        An array containing True for each valid business day, and
-        False for the others.
+        An array with the same shape as ``dates``, containing True for
+        each valid business day, and False for the others.
 
     See Also
     --------
@@ -6102,7 +6102,8 @@ add_newdoc('numpy.core.multiarray', 'busday_offset',
     Returns
     -------
     out : array of datetime64[D]
-        An array containing the dates with offsets applied.
+        An array with a shape from broadcasting ``dates`` and ``offsets``
+        together, containing the dates with offsets applied.
 
     See Also
     --------
@@ -6174,7 +6175,8 @@ add_newdoc('numpy.core.multiarray', 'busday_count',
     Returns
     -------
     out : array of int64
-        An array containing the number of business days between
+        An array with a shape from broadcasting ``begindates`` and ``enddates``
+        together, containing the number of business days between
         the begin and end dates.
 
     See Also
diff --git a/numpy/core/src/multiarray/_datetime.h b/numpy/core/src/multiarray/_datetime.h
index 12e833378..8a9ffff7b 100644
--- a/numpy/core/src/multiarray/_datetime.h
+++ b/numpy/core/src/multiarray/_datetime.h
@@ -47,7 +47,10 @@ convert_datetimestruct_to_datetime(PyArray_DatetimeMetaData *meta,
                                     const npy_datetimestruct *dts,
                                     npy_datetime *out);
 
-/* Extracts the month number from a 'datetime64[D]' value */
+/*
+ * Extracts the month number, within the current year,
+ * from a 'datetime64[D]' value. January is 1, etc.
+ */
 NPY_NO_EXPORT int
 days_to_month_number(npy_datetime days);
 
@@ -62,15 +65,6 @@ parse_datetime_metadata_from_metastr(char *metastr, Py_ssize_t len,
 
 
 /*
- * This function returns a reference to a capsule
- * which contains the datetime metadata parsed from a metadata
- * string. 'metastr' should be NULL-terminated, and len should
- * contain its string length.
- */
-NPY_NO_EXPORT PyObject *
-parse_datetime_metacobj_from_metastr(char *metastr, Py_ssize_t len);
-
-/*
  * Converts a datetype dtype string into a dtype descr object.
  * The "type" string should be NULL-terminated, and len should
  * contain its string length.
diff --git a/numpy/core/src/multiarray/ctors.c b/numpy/core/src/multiarray/ctors.c
index 0ae743481..8d4a7430b 100644
--- a/numpy/core/src/multiarray/ctors.c
+++ b/numpy/core/src/multiarray/ctors.c
@@ -1690,7 +1690,16 @@ PyArray_FromAny(PyObject *op, PyArray_Descr *newtype, int min_depth,
             }
         }
     }
-    /* Treat datetime generic units with the same idea as flexible strings */
+    /*
+     * Treat datetime generic units with the same idea as flexible strings.
+     *
+     * Flexible strings, for example the dtype 'str', use size zero as a
+     * signal indicating that they represent a "generic string type" instead
+     * of a string type with the size already baked in. The generic unit
+     * plays the same role, indicating that it's a "generic datetime type",
+     * and the actual unit should be filled in when needed just like the
+     * actual string size should be filled in when needed.
+     */
     else if (newtype != NULL && newtype->type_num == NPY_DATETIME) {
         PyArray_DatetimeMetaData *meta =
                     get_datetime_metadata_from_dtype(newtype);
diff --git a/numpy/core/src/multiarray/datetime.c b/numpy/core/src/multiarray/datetime.c
index a9f2f6749..78a5032f5 100644
--- a/numpy/core/src/multiarray/datetime.c
+++ b/numpy/core/src/multiarray/datetime.c
@@ -1505,8 +1505,8 @@ get_datetime_conversion_factor(PyArray_DatetimeMetaData *src_meta,
     /* If something overflowed, make both num and denom 0 */
     if (denom == 0) {
         PyErr_Format(PyExc_OverflowError,
-                    "Integer overflow getting a conversion factor between "
-                    "NumPy datetime unit %s and %s",
+                    "Integer overflow while computing the conversion "
+                    "factor between NumPy datetime units %s and %s",
                     _datetime_strings[src_base],
                     _datetime_strings[dst_base]);
         *out_num = 0;
@@ -4660,7 +4660,7 @@ datetime_arange(PyObject *start, PyObject *stop, PyObject *step,
     }
     else {
         PyErr_SetString(PyExc_ValueError,
-                    "arange: step may not be zero");
+                    "arange: step cannot be zero");
         return NULL;
     }