Bring back docs

lib/ui/window/platform_configuration.h

@@ -261,7 +261,9 @@ class PlatformConfiguration final {
   //----------------------------------------------------------------------------
   /// @brief      Notify the framework that a new view is available.
   ///
-  ///             The implicit view should also be added with this method.
+  ///             A view must be added before other methods can refer to it,
+  ///             including the implicit view. Adding a view that has been
+  ///             added triggers assertion.
   ///
   /// @param[in]  view_id           The ID of the new view.
   /// @param[in]  viewport_metrics  The initial viewport metrics for the view.
@@ -271,8 +273,7 @@ class PlatformConfiguration final {
   //----------------------------------------------------------------------------
   /// @brief      Notify the framework that a view is no longer available.
   ///
-  ///             The implicit view should not be removed with this method,
-  ///             since it should never be removed.
+  ///             Removing a view that has not been added triggers assertion.
   ///
   /// @param[in]  view_id  The ID of the view.
   ///

runtime/runtime_controller.h

@@ -166,7 +166,9 @@ class RuntimeController : public PlatformConfigurationClient {
   //----------------------------------------------------------------------------
   /// @brief      Notify the isolate that a new view is available.
   ///
-  ///             The implicit view should also be added with this method.
+  ///             A view must be added before other methods can refer to it,
+  ///             including the implicit view. Adding a view that has been
+  ///             added triggers assertion.
   ///
   /// @param[in]  view_id           The ID of the new view.
   /// @param[in]  viewport_metrics  The initial viewport metrics for the view.
@@ -176,8 +178,7 @@ class RuntimeController : public PlatformConfigurationClient {
   //----------------------------------------------------------------------------
   /// @brief      Notify the isolate that a view is no longer available.
   ///
-  ///             The implicit view should not be removed with this method,
-  ///             since it should never be removed.
+  ///             Removing a view that has not been added triggers assertion.
   ///
   /// @param[in]  view_id  The ID of the view.
   ///

shell/common/engine.h

@@ -678,7 +678,9 @@ class Engine final : public RuntimeDelegate, PointerDataDispatcher::Delegate {
   //----------------------------------------------------------------------------
   /// @brief      Notify the Flutter application that a new view is available.
   ///
-  ///             The implicit view should also be added with this method.
+  ///             A view must be added before other methods can refer to it,
+  ///             including the implicit view. Adding a view that has been
+  ///             added triggers assertion.
   ///
   /// @param[in]  view_id           The ID of the new view.
   /// @param[in]  viewport_metrics  The initial viewport metrics for the view.
@@ -689,8 +691,8 @@ class Engine final : public RuntimeDelegate, PointerDataDispatcher::Delegate {
   /// @brief      Notify the Flutter application that a view is no
   ///             longer available.
   ///
-  ///             The implicit view should not be removed with this method,
-  ///             since it should never be removed.
+  ///             Removing a view that has not been not added triggers
+  ///             assertion.
   ///
   /// @param[in]  view_id  The ID of the view.
   ///

shell/common/rasterizer.h

@@ -209,8 +209,9 @@ class Rasterizer final : public SnapshotDelegate,
   ///
   ///             This method should be called a view is removed.
   ///
-  ///             Resources for a view is allocated the first time the
-  ///             rasterizer encouters this view ID.
+  ///             The rasterizer don't need views to be registered. Last-frame
+  ///             states for views are recorded when layer trees are rasterized
+  ///             to the view and used during `Rasterizer::DrawLastLayerTree`.
   ///
   /// @param[in]  view_id  The ID of the view.
   ///

shell/common/shell.h

@@ -298,12 +298,13 @@ class Shell final : public PlatformView::Delegate,
   ///
   bool IsSetup() const;
 
-  /// @brief  Adds a non-implicit view.
+  /// @brief  Allocates resources for a new non-implicit view.
   ///
-  ///         This method returns immediately and does not wait for the tasks
-  ///         on the UI thread to finish. This is because operations are either
-  ///         initiated from the UI thread (such as rendering), or are sent as a
-  ///         posted task that is queued.
+  ///         This method returns immediately and does not wait for the tasks on
+  ///         the UI thread to finish. This is safe because operations are
+  ///         either initiated from the UI thread (such as rendering), or are
+  ///         sent as posted tasks that are queued. In either case, it's ok for
+  ///         the engine to have views that the Dart VM doesn't.
   ///
   ///         The implicit view should never be added with this function.
   ///         Instead, it is added internally on Shell initialization depending
@@ -315,10 +316,10 @@ class Shell final : public PlatformView::Delegate,
   ///
   void AddView(int64_t view_id, const ViewportMetrics& viewport_metrics);
 
-  /// @brief  Removes a non-implicit view.
+  /// @brief  Deallocates resources for a non-implicit view.
   ///
-  ///         This method waits for the tasks on the rasterizer thread and the
-  ///         UI thread to finish before returning.
+  ///         This method waits for the tasks on the UI thread to finish before
+  ///         returning.
   ///
   ///         The implicit view should never be removed. Trying to remove
   ///         `kFlutterImplicitViewId` is a no-op with warning.