DOC: improve removal for julian dates [ci doc]

jklymak · jklymak · commit 4e5c68bc6b5c · 2023-09-22T18:12:51.000-07:00
diff --git a/doc/api/next_api_changes/removals/26852-OG.rst b/doc/api/next_api_changes/removals/26852-OG.rst
@@ -2,4 +2,10 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ... of the `.dates` module are removed without replacements. These were
-undocumented and not exported.
+undocumented and not exported.  Julian dates in Matplotlib were calculated from the
+Julian date epoch:
+``jdate = (date - np.datetime64('-4713-11-24T12:00')) / np.timedelta64(1, 'D')``,
+A Julian date was converted to datetime as
+``date = np.timedelta64(int(jdate * 24 * 3600), 's') + np.datetime64('-4713-11-24T12:00')``.
+where some care needs to be taken with the accuracy of the ``timedelta64``.  Given the various
+definitions of Julian date, users should exercise caution using these values.
