I understand the use case for `org-file-clear-cache'. My suggestion is
to remove that need by clearing cache automatically. Of course, the
drawback is the cache is cleared more often than necessary. Users could
get very surprising results if they forget to call this function. So it
might be a good idea to call it from time to time, on user's behalf.
`org-file-contents' is a developer-facing function. I don't really see
a good place in the manual for it. That's the problem of
`org-file-clear-cache', which is really an implementation detail users
shouldn't care about.
Here's another idea: call it from `org-mode-restart'. So cache is reset
whenever `C-c C-c' is pressed on a keyword. So we don't need to document
the function anymore. Instead, we could drop a note about the cache in
(info "(org) The very busy C-c C-c key").
OK. Then the following at least doesn't have the overhead of creating
a string:
Also, mind the full stop at the end of the comments.
Kaushal Modi