Add example of stale cached content behavior

Signed-off-by: Daniel Carl Jones <[email protected]>

doc/SEMANTICS.md

@@ -77,6 +77,10 @@ Mountpoint also offers optional metadata and object content caching which can be
 see the [caching section of the configuration documentation](./CONFIGURATION.md#caching) for more information.
 When opting into caching, the consistency model is relaxed and you may see stale entries until they have expired.
 Stale entries may live as long as the cache's metadata time-to-live (TTL).
+For example, without caching it was not possible to read stale data if the file was opened after it was updated or deleted.
+With caching, it is now possible to open a file for a stale object.
+Reads may either succeed returning any cached object content or return I/O errors for accesses to uncached object content.
+However, it is not possible for object content from two different objects to be returned for the same file handle.
 
 Mountpoint allows multiple readers to access the same object at the same time. However, a new file can only be written to sequentially and by one writer at a time. New files that are being written are not available for reading until the writing application closes the file and Mountpoint finishes uploading it to S3. If you have multiple Mountpoint mounts for the same bucket, on the same or different hosts, there is no coordination between writes to the same object. We recommend that your application does not write to the same object from multiple instances at the same time.