[Render Frame Host] Document IsCurrent().

Before this patch, Chromium developers could call
RenderFrameHost::IsCurrent() to check whether the frame is about to be
deleted without understanding that IsCurrent() can return false
temporarily, e.g., when in bfcache.

This patch adds comments to RenderFrameHost::IsCurrent() and
WebContents::FromRenderFrameHost() that explain how IsCurrent() should
be called before FromRenderFrameHost().

After this patch, it should be more clear to Chromium developers that
IsCurrent() should be used to check whether FromRenderFrameHost() can be
called.

Change-Id: I7bba60ca7e73e3ff5c4320ffe8f3ee1be00393be
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2461590
Commit-Queue: Alex Moshchuk <alexmos@chromium.org>
Reviewed-by: Alex Moshchuk <alexmos@chromium.org>
Reviewed-by: Alexander Timin <altimin@chromium.org>
Cr-Commit-Position: refs/heads/master@{#818694}

content/public/browser/render_frame_host.h

@@ -389,6 +389,12 @@ class CONTENT_EXPORT RenderFrameHost : public IPC::Listener,
   //  deletion").
   // In both cases, IsCurrent() becomes false for this frame and all its
   // children.
+  //
+  // This method should be called before trying to display some UI to the user
+  // on behalf of the given RenderFrameHost (or when crossing document / tab
+  // boundary in general, e.g. when using WebContents::FromRenderFrameHost) to
+  // check if the given RenderFrameHost is currently being displayed in a given
+  // tab.
   virtual bool IsCurrent() = 0;
 
   // Returns true iff the RenderFrameHost is inactive i.e., when the

content/public/browser/web_contents.h

@@ -258,6 +258,10 @@ class WebContents : public PageNavigator,
 
   // Returns the WebContents for the RenderFrameHost. It is unsafe to call this
   // function with an invalid (e.g. destructed) `rfh`.
+  // Warning: Be careful when `rfh->IsCurrent()` is false, since this implies
+  // that `rfh` may not be visible to the user (in bfcache or pending deletion),
+  // so it should not be triggering state changes that affect the whole
+  // WebContents.
   CONTENT_EXPORT static WebContents* FromRenderFrameHost(RenderFrameHost* rfh);
 
   // Returns the WebContents associated with the |frame_tree_node_id|. This may