Thanks for another round of review.

I have attached a patch, rebased to master and with all suggestions
implemented.

There are some additional changes in the patch this time:
- Prevent org-edit-special from attempting to open the "file" for editing
if the value is a URL.
- Silence byte-compiler for ffap-url-regexp. We do a require, but the
byte-compiler still complains of a free variable.
- Update org.texi at few places (first time editing a texi)

On Fri, May 26, 2017 at 3:47 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> 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.
>

I liked your C-c C-c idea below! :)


> `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.
>

Understood.


> 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").
>

Done!


> OK. Then the following at least doesn't have the overhead of creating
> a string:
>

Integrated. Thanks!

Also, mind the full stop at the end of the comments.
>

Will do.
-- 

Kaushal Modi