[iOS] Add documentation of the architecture.

Add documentation for part of the architecture of Chrome on iOS. In
particular how ApplicationContext, ChromeBrowserState, BrowserList,
Browser, WebStateList and WebState are related and used.

Bug: none
Change-Id: I1354044f6be00eb04b8f9c147190399aa16f7a62
Reviewed-on: https://chromium-review.googlesource.com/603720
Commit-Queue: Sylvain Defresne <sdefresne@chromium.org>
Reviewed-by: Mark Cogan <marq@chromium.org>
Cr-Commit-Position: refs/heads/master@{#493424}

docs/ios/objects.md

@@ -0,0 +1,108 @@
+
+# ApplicationContext
+
+ApplicationContext is a global singleton. It gives access to other global
+objects and settings that are shared by all user sessions. Those settings
+are called "local settings" as they are not synchronised and only affect
+the current device (as the settings are shared by all sessions there is
+no account to sync them to).
+
+The corresponding object on desktop is BrowserProcess.
+
+# ChromeBrowserState
+
+ChromeBrowserState objects correspond to a user browsing session. There is
+one for the off-the-record session, and one per user created in the UI (at
+the time this document is written, there is only one user on iOS so at most
+there are two ChromeBrowserStates).
+
+The ChromeBrowserState objects are owned by the ChromeBrowserStateManager
+that can be accessed via the ApplicationContext. It is possible to access
+the off-the-record ChromeBrowserState from a non-incognito instance.
+
+Each ChromeBrowserState, including the off-the-record ChromeBrowserState,
+have a directory used to store some state (current session, settings, ...).
+The settings may be synchronised if the user has logged in and has enabled
+the synchronisation (thus they are non-local).
+
+The off-the-record ChromeBrowserState needs to record some state because the
+application can be killed at any time when the application is in the background
+and the state needs to be persisted as this termination should be transparent to
+the user. The state is deleted when the last off-the-record tab is closed
+and the off-the-record ChromeBrowserState is deleted.
+
+The ChromeBrowserStates support attaching base::SupportsUserData::Data
+objects to tie some objects to the ChromeBrowserState lifetime. Check the
+documentation of base::SupportsUserData for more information.
+
+A special case of base::SupportsUserData::Data is the KeyedService. They
+are managed by the BrowserStateKeyedServiceFactory infrastructure. This
+infrastructure allows to declare dependencies between services and ensure
+that they are created and destroyed in an order compatible with those
+dependencies.
+
+It should never be required to extend ChromeBrowserState. Instead consider
+adding a preference to the settings, a base::SupportsUserData::Data if the
+change is just to add some data or a KeyedService if behaviour needs to be
+added.
+
+The corresponding object on desktop is Profile.
+
+# BrowserList
+
+BrowserList is a container owning Browser instances. It is owned by the
+ChromeBrowserState and each ChromeBrowserState has one associated
+BrowserList.
+
+The corresponding object on desktop is BrowserList but the API is
+different. On desktop, it is a singleton and it points to all the
+Browsers instances whereas on iOS there is one per ChromeBrowserState.
+
+# Browser
+
+Browser is the model for a window containing multiple tabs. Currently
+on iOS there is only one window per ChromeBrowserState, thus there is
+a single Browser per BrowserList.
+
+The Browser owns a WebStateList and thus indirectly owns all the tabs
+(aka WebState and their associated tab helpers).
+
+The corresponding object on desktop is Browser.
+
+# WebStateList
+
+WebStateList represents a list of WebStates. It maintains a notion of
+an active WebState and opener-opened relationship between WebStates.
+
+The WebStateList exposes an API to observe modification to the list of
+WebStates (additions, moves, removals, replacements).
+
+The WebStateList also has a delegate that is invoked when a WebState
+when WebStates are added to or removed from the WebStateList. This is
+used to attach all necessary tab helpers to the WebState.
+
+There is a legacy interface (TabModel) that is used to represent a list of
+Tabs and added some behaviour. This interface is obsolete and is slowly
+being removed, prefer to use WebStateList if possible.
+
+The corresponding object on desktop is TabStripModel.
+
+# WebState
+
+WebState wraps a WKWebView and allows navigation. A WebState can have
+many tab helpers attached. A WebState in a WebStateList corresponds to
+an open tab and the corresponding tab helpers can be assumed to be
+created.
+
+As the tab helpers are only added to a WebState upon insertion into a
+WebStateList (or in a limited number of code paths), code should not
+assume that a tab helper will be available when using a WebState but
+instead should support the tab helper being unavailable.
+
+A WebState and all the attached tab helpers are sometimes called a
+tab (because they implement what the user sees and interacts with in
+a browser tab). There currently is a Tab interface but it is a legacy
+object that is deprecated and is slowly being removed. If possible,
+prefer to use WebState directly instead of Tab.
+
+The corresponding object on desktop is WebContents.