Further publicize MPArch documentation

We add a description of what "MPArch" means to docs/frame_trees.md and
link to further external design docs. We reference this doc in relevant
locations in the content public API.

We also update the comment on the WebContents class to no longer
incorrectly describe WebContents and NavigationController as 1:1.

Bug: 1267508
Change-Id: Ib0581bad10726c14e432d631f1a2106764238fb6
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4026495
Commit-Queue: Kevin McNee <mcnee@chromium.org>
Reviewed-by: Alexander Timin <altimin@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1074972}

content/browser/web_contents/web_contents_impl.h

@@ -310,6 +310,7 @@ class CONTENT_EXPORT WebContentsImpl : public WebContents,
 
   // Returns the primary FrameTree for this WebContents (as opposed to the
   // ones held by MPArch features like Prerender or Fenced Frame).
+  // See docs/frame_trees.md for more details.
   FrameTree& GetPrimaryFrameTree() { return primary_frame_tree_; }
 
   // Whether the initial empty page of this view has been accessed by another

content/public/browser/navigation_controller.h

@@ -70,7 +70,7 @@ struct OpenURLParams;
 // WebContents, so there can be multiple NavigationControllers associated with
 // a WebContents. However only the primary one, and the
 // NavigationEntries/events originating from it, is exposed to //content
-// embedders.
+// embedders. See docs/frame_trees.md for more details.
 class NavigationController {
  public:
   using DeletionPredicate =

content/public/browser/navigation_handle.h

@@ -115,6 +115,7 @@ class CONTENT_EXPORT NavigationHandle : public base::SupportsUserData {
   // additional frame trees for prerendering pages in addition to the primary
   // frame tree (holding the page currently shown to the user). The return
   // value remains constant over the navigation lifetime.
+  // See docs/frame_trees.md for more details.
   virtual bool IsInPrimaryMainFrame() const = 0;
 
   // Whether the navigation is taking place in a main frame which does not have

content/public/browser/page.h

@@ -47,6 +47,7 @@ namespace content {
 // additional FrameTrees which will have their own associated Page. Please take
 // into consideration when assuming that Page is appropriate for storing
 // something that's common for all frames you see on a tab.
+// See docs/frame_trees.md for more details.
 
 // NOTE: Depending on the process model, the cross-origin iframes are likely to
 // be hosted in a different renderer process than the main document, so a given

content/public/browser/render_frame_host.h

@@ -318,6 +318,7 @@ class CONTENT_EXPORT RenderFrameHost : public IPC::Listener,
   // Note that this may be different from getting the WebContents' primary main
   // frame. For example, if `this` is in a bfcached or prerendered page, this
   // will return the cached/prerendered page's main RenderFrameHost.
+  // See docs/frame_trees.md for more details.
   virtual RenderFrameHost* GetOutermostMainFrame() = 0;
 
   // Fenced frames (meta-bug https://crbug.com/1111084):

content/public/browser/web_contents.h

@@ -120,11 +120,10 @@ class PreloadingAttempt;
 // https://www.chromium.org/developers/design-documents/multi-process-architecture
 // .
 //
-// Each WebContents has exactly one NavigationController; each
-// NavigationController belongs to one WebContents. The NavigationController can
-// be obtained from GetController(), and is used to load URLs into the
-// WebContents, navigate it backwards/forwards, etc. See navigation_controller.h
-// for more details.
+// Each WebContents has a `NavigationController`, which can be obtained from
+// `GetController()`, and is used to load URLs into the WebContents, navigate
+// it backwards/forwards, etc.
+// See navigation_controller.h for more details.
 class WebContents : public PageNavigator,
                     public base::SupportsUserData {
  public:
@@ -368,6 +367,7 @@ class WebContents : public PageNavigator,
   // Returns the primary main frame for the currently active page. Always
   // non-null except during WebContents destruction. This WebContents may
   // have additional main frames for prerendered pages, bfcached pages, etc.
+  // See docs/frame_trees.md for more details.
   virtual RenderFrameHost* GetPrimaryMainFrame() = 0;
 
   // Returns the current page in the primary frame tree of this WebContents.
@@ -401,6 +401,7 @@ class WebContents : public PageNavigator,
   // reference to RenderFrameHost or a Page (e.g. each IPC from the renderer
   // process should be associated with a particular RenderFrameHost), it should
   // be used instead of getting the primary page from the WebContents.
+  // See docs/frame_trees.md for more details.
   virtual Page& GetPrimaryPage() = 0;
 
   // Returns the focused frame for the primary page or an inner page thereof.

docs/frame_trees.md

@@ -99,6 +99,19 @@ In the case of nested frame trees, the RenderFrameHost corresponding to the
 hosting document owns the inner FrameTree (possibly through an intermediate
 object, as is the case for content::FencedFrame).
 
+## "MPArch"
+
+"MPArch," short for Multiple Page Architecture, refers to the name of the
+project that introduced the capability of having multiple FrameTrees in a
+single WebContents.
+
+You may also see comments which describe features relying on multiple FrameTrees
+in terms of MPArch (e.g. "ignore navigations from MPArch pages"). These are in
+reference to "non-primary" frame trees as described above.
+
+See the original [design doc](https://docs.google.com/document/d/1NginQ8k0w3znuwTiJ5qjYmBKgZDekvEPC22q0I4swxQ/edit?usp=sharing)
+for further info.
+
 ## Footnotes
 
 <a name="footnote_1"></a>1: GuestViews (embedding of a WebContents inside another WebContents) are