From 70f5a07fe6ac04f35ff81c7b4806f35649e2043d Mon Sep 17 00:00:00 2001
From: Chinmay Garde <chinmaygarde@google.com>
Date: Mon, 30 Mar 2020 00:20:54 -0700
Subject: [PATCH] Document flutter::DartVMData. (#17392)

---
 runtime/dart_vm_data.h | 46 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/runtime/dart_vm_data.h b/runtime/dart_vm_data.h
index 0f054bf55..49ddd3168 100644
--- a/runtime/dart_vm_data.h
+++ b/runtime/dart_vm_data.h
@@ -10,19 +10,65 @@
 
 namespace flutter {
 
+//------------------------------------------------------------------------------
+/// @brief      Provides thread-safe access to data that is necessary to
+///             bootstrap a new Dart VM instance. All snapshots referenced by
+///             this object are read-only.
+///
 class DartVMData {
  public:
+  //----------------------------------------------------------------------------
+  /// @brief      Creates a new instance of `DartVMData`. Both the VM and
+  ///             isolate snapshot members are optional and may be `nullptr`. If
+  ///             `nullptr`, the snapshot resolvers present in the settings
+  ///             object are used to infer the snapshots. If the snapshots
+  ///             cannot be inferred from the settings object, this method
+  ///             return `nullptr`.
+  ///
+  /// @param[in]  settings          The settings used to infer the VM and
+  ///                               isolate snapshots if they are not provided
+  ///                               directly.
+  /// @param[in]  vm_snapshot       The VM snapshot or `nullptr`.
+  /// @param[in]  isolate_snapshot  The isolate snapshot or `nullptr`.
+  ///
+  /// @return     A new instance of VM data that can be used to bootstrap a Dart
+  ///             VM. `nullptr` if the snapshots are not provided and cannot be
+  ///             inferred from the settings object.
+  ///
   static std::shared_ptr<const DartVMData> Create(
       Settings settings,
       fml::RefPtr<DartSnapshot> vm_snapshot,
       fml::RefPtr<DartSnapshot> isolate_snapshot);
 
+  //----------------------------------------------------------------------------
+  /// @brief      Collect the DartVMData instance.
+  ///
   ~DartVMData();
 
+  //----------------------------------------------------------------------------
+  /// @brief      The settings object from which the Dart snapshots were
+  ///             inferred.
+  ///
+  /// @return     The settings.
+  ///
   const Settings& GetSettings() const;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Gets the VM snapshot. This can be in the call to bootstrap
+  ///             the Dart VM via `Dart_Initialize`.
+  ///
+  /// @return     The VM snapshot.
+  ///
   const DartSnapshot& GetVMSnapshot() const;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Get the isolate snapshot necessary to launch isolates in the
+  ///             Dart VM. The Dart VM instance in which these isolates are
+  ///             launched must be the same as the VM created using snapshot
+  ///             accessed via `GetVMSnapshot`.
+  ///
+  /// @return     The isolate snapshot.
+  ///
   fml::RefPtr<const DartSnapshot> GetIsolateSnapshot() const;
 
  private:
-- 
GitLab