Added detailed cache note

Author: seanlaw

stumpy/cache.py

@@ -252,8 +252,15 @@ def save():
 
     Notes
     -----
-    The cache is never cleared before saving/overwriting and may be explicitly
-    cleared by calling `cache.clear()` before saving.
+    The cache is never cleared before saving/overwriting and may be explicitly cleared
+    by calling `cache.clear()` before saving. If `cache.save()` is called for the first
+    time (before any `njit` function is called) then only the `.nbi` files (i.e., the
+    "cache index") for all `njit` functions are saved. As each `njit` function (and
+    sub-functions) is called then their corresponding `.nbc` file (i.e., "object code")
+    is saved. Each `.nbc` file will only be saved after its `njit` function is called
+    once. However, subsequent calls to `cache.save()` (after clearing the cache via
+    `cache.clear()`) will automatically save BOTH the `.nbi` files as well as the `.nbc`
+    files as long as their `njit` function has been called at least once. 
     """
     if numba.config.DISABLE_JIT:
         msg = "Could not save/cache function because NUMBA JIT is disabled"

tests/test_cache.py

@@ -16,9 +16,9 @@ def test_cache_save_after_clear():
     cache_dir = "stumpy/__pycache__"
 
     cache.clear(cache_dir)
-    cache.save()
+    cache.save()  # Saves nbi files only until njit funcs are called for the first time
 
-    stump(T, m)
+    stump(T, m)  # Saves nbc files, subsequent saves will write both nbi and nbc files
     ref_cache = cache._get_cache(cache_dir)
 
     if numba.config.DISABLE_JIT:
@@ -28,9 +28,8 @@ def test_cache_save_after_clear():
 
     cache.clear(cache_dir)
     assert len(cache._get_cache(cache_dir)) == 0
-    cache.save()
+    cache.save()  # Save both nbi and nbc files without needing to call `stump` function
 
-    # stump(T, m)
     comp_cache = cache._get_cache(cache_dir)
 
     assert sorted(ref_cache) == sorted(comp_cache)