Bug 957992 - Document toolbar high-level architecture (r=margaret)

mobile/android/base/toolbar/BrowserToolbar.java

@@ -62,6 +62,23 @@ import java.util.ArrayList;
 import java.util.EnumSet;
 import java.util.List;
 
+/**
+* {@code BrowserToolbar} is single entry point for users of the toolbar
+* subsystem i.e. this should be the only import outside the 'toolbar'
+* package.
+*
+* {@code BrowserToolbar} serves at the single event bus for all
+* sub-components in the toolbar. It tracks tab events and gecko messages
+* and update the state of its inner components accordingly.
+*
+* It has two states, display and edit, which are controlled by
+* ToolbarEditLayout and ToolbarDisplayLayout. In display state, the toolbar
+* displays the current state for the selected tab. In edit state, it shows
+* a text entry for searching bookmarks/history. {@code BrowserToolbar}
+* provides public API to enter, cancel, and commit the edit state as well
+* as a set of listeners to allow {@code BrowserToolbar} users to react
+* to state changes accordingly.
+*/
 public class BrowserToolbar extends GeckoRelativeLayout
                             implements Tabs.OnTabsChangedListener,
                                        GeckoMenu.ActionItemBarPresenter,

mobile/android/base/toolbar/ToolbarDisplayLayout.java

@@ -47,17 +47,38 @@ import java.util.Arrays;
 import java.util.EnumSet;
 import java.util.List;
 
+/**
+* {@code ToolbarDisplayLayout} is the UI for when the toolbar is in
+* display state. It's used to display the state of the currently selected
+* tab. It should always be updated through a single entry point
+* (updateFromTab) and should never track any tab events or gecko messages
+* on its own to keep it as dumb as possible.
+*
+* The UI has two possible modes: progress and display which are triggered
+* when UpdateFlags.PROGRESS is used depending on the current tab state.
+* The progress mode is triggered when the tab is loading a page. Display mode
+* is used otherwise.
+*
+* {@code ToolbarDisplayLayout} is meant to be owned by {@code BrowserToolbar}
+* which is the main event bus for the toolbar subsystem.
+*/
 public class ToolbarDisplayLayout extends GeckoLinearLayout
                                   implements Animation.AnimationListener {
 
     private static final String LOGTAG = "GeckoToolbarDisplayLayout";
 
+    // To be used with updateFromTab() to allow the caller
+    // to give enough context for the requested state change.
     enum UpdateFlags {
         TITLE,
         FAVICON,
         PROGRESS,
         SITE_IDENTITY,
         PRIVATE_MODE,
+
+        // Disable any animation that might be
+        // triggered from this state change. Mostly
+        // used on tab switches, see BrowserToolbar.
         DISABLE_ANIMATIONS
     }
 

mobile/android/base/toolbar/ToolbarEditLayout.java

@@ -25,6 +25,12 @@ import android.view.View.OnFocusChangeListener;
 import android.view.inputmethod.InputMethodManager;
 import android.widget.ImageButton;
 
+/**
+* {@code ToolbarEditLayout} is the UI for when the toolbar is in
+* edit state. It controls a text entry ({@code ToolbarEditText})
+* and its matching 'go' button which changes depending on the
+* current type of text in the entry.
+*/
 public class ToolbarEditLayout extends GeckoLinearLayout {
 
     private final ToolbarEditText mEditText;

mobile/android/base/toolbar/ToolbarEditText.java

@@ -30,11 +30,20 @@ import android.view.View.OnKeyListener;
 import android.view.inputmethod.EditorInfo;
 import android.view.inputmethod.InputMethodManager;
 
+/**
+* {@code ToolbarEditText} is the text entry used when the toolbar
+* is in edit state. It handles all the necessary input method machinery
+* as well as the tracking of different text types (empty, search, or url).
+* It's meant to be owned by {@code ToolbarEditLayout}.
+*/
 public class ToolbarEditText extends CustomEditText
                              implements AutocompleteHandler {
 
     private static final String LOGTAG = "GeckoToolbarEditText";
 
+    // Used to track the current type of content in the
+    // text entry so that ToolbarEditLayout can update its
+    // state accordingly.
     enum TextType {
         EMPTY,
         SEARCH_QUERY,