Add comments/docstrings about cacheing in get_class_attribute_docstrings

Author: rwb27

src/labthings_fastapi/base_descriptor.py

@@ -295,6 +295,15 @@ class Example:
         just paste the example above into a Python interpreter). In that case,
         an empty dictionary is returned.
 
+        The same limitation means dynamically defined classes will result in
+        an empty dictionary.
+
+    .. note::
+
+        This function uses a cache, so subsequent calls on the same class will
+        return a cached value. As dynamic classes are not supported, this is
+        not expected to be a problem.
+
     :param cls: The class to inspect
     :return: A mapping of attribute names to docstrings. Note that this will be
         wrapped in a `types.MappingProxyType` to prevent accidental modification.

tests/test_base_descriptor.py

@@ -45,6 +45,10 @@ def test_docstrings_are_cached():
     """Check that the docstrings aren't being regenerated every time."""
     docs1 = get_class_attribute_docstrings(Example)
     docs2 = get_class_attribute_docstrings(Example)
+    # The dictionary of attribute docstrings is cached, keyed on the
+    # class. The test below checks the same object is returned, not
+    # just one with the same values in it - this implies the cache
+    # is working.
     assert docs1 is docs2