Document the design goals and scopes

msal_extensions/token_cache.py

@@ -15,7 +15,30 @@
 logger = logging.getLogger(__name__)
 
 class PersistedTokenCache(msal.SerializableTokenCache):
-    """A token cache using given persistence layer, coordinated by a file lock."""
+    """A token cache backed by a persistence layer, coordinated by a file lock,
+    to sustain a certain level of multi-process concurrency for a desktop app.
+
+    The scenario is that multiple instances of same desktop app
+    (or even multiple different apps)
+    create their own ``PersistedTokenCache`` instances,
+    which are all backed by the same token cache file on disk
+    (known as a persistence). The goal is to have Single Sign On (SSO).
+
+    Each instance of ``PersistedTokenCache`` holds a snapshot of the token cache
+    in memory.
+    Each :func:`~find` call will
+    automatically reload token cache from the persistence when necessary,
+    so that it will have fresh data.
+    Each :func:`~modify` call will
+    automatically reload token cache from the persistence when necessary,
+    so that new writes will be appended on top of latest token cache data,
+    and then the new data will be immediately flushed back to the persistence.
+
+    Note: :func:`~deserialize` and :func:`~serialize` remain the same
+    as their counterparts in the parent class ``msal.SerializableTokenCache``.
+    In other words, they do not have the "reload from persistence if necessary"
+    nor the "flush back to persistence" behavior.
+    """
 
     def __init__(self, persistence, lock_location=None):
         super(PersistedTokenCache, self).__init__()