Document //flutter/runtime/dart_snapshot.h (flutter#13196)

Related to flutter#42778

Author: chinmaygarde

runtime/dart_snapshot.h

@@ -14,27 +14,140 @@
 
 namespace flutter {
 
+//------------------------------------------------------------------------------
+/// @brief      A read-only Dart heap snapshot, or, read-executable mapping of
+///             AOT compiled Dart code.
+///
+///             To make Dart code startup more performant, the Flutter tools on
+///             the host snapshot the state of the Dart heap at specific points
+///             and package the same with the Flutter application. When the Dart
+///             VM on the target is configured to run AOT compiled Dart code,
+///             the tools also compile the developer's Flutter application code
+///             to target specific machine code (instructions). This class deals
+///             with the mapping of both these buffers at runtime on the target.
+///
+///             A Flutter application typically needs two instances of this
+///             class at runtime to run Dart code. One instance is for the VM
+///             and is called the "core snapshot". The other is the isolate
+///             and called the "isolate snapshot". Different root isolates can
+///             be launched with different isolate snapshots.
+///
+///             These snapshots are typically memory-mapped at runtime, or,
+///             referenced directly as symbols present in Mach or ELF binaries.
+///
+///             In the case of the core snapshot, the snapshot is collected when
+///             the VM shuts down. The isolate snapshot is collected when the
+///             isolate group shuts down.
+///
 class DartSnapshot : public fml::RefCountedThreadSafe<DartSnapshot> {
  public:
+  //----------------------------------------------------------------------------
+  /// The symbol name of the heap data of the core snapshot in a dynamic library
+  /// or currently loaded process.
+  ///
   static const char* kVMDataSymbol;
+  //----------------------------------------------------------------------------
+  /// The symbol name of the instructions data of the core snapshot in a dynamic
+  /// library or currently loaded process.
+  ///
   static const char* kVMInstructionsSymbol;
+  //----------------------------------------------------------------------------
+  /// The symbol name of the heap data of the isolate snapshot in a dynamic
+  /// library or currently loaded process.
+  ///
   static const char* kIsolateDataSymbol;
+  //----------------------------------------------------------------------------
+  /// The symbol name of the instructions data of the isolate snapshot in a
+  /// dynamic library or currently loaded process.
+  ///
   static const char* kIsolateInstructionsSymbol;
 
+  //----------------------------------------------------------------------------
+  /// @brief      From the fields present in the given settings object, infer
+  ///             the core snapshot.
+  ///
+  /// @attention  Depending on the runtime mode of the Flutter application and
+  ///             the target that Flutter is running on, a complex fallback
+  ///             mechanism is in place to infer the locations of each snapshot
+  ///             buffer. If the caller wants to explicitly specify the buffers
+  ///             of the core snapshot, the `Settings::vm_snapshot_data` and
+  ///             `Settings::vm_snapshots_instr` mapping fields may be used.
+  ///             This specification takes precedence over all fallback search
+  ///             paths.
+  ///
+  /// @param[in]  settings  The settings to infer the core snapshot from.
+  ///
+  /// @return     A valid core snapshot or nullptr.
+  ///
   static fml::RefPtr<DartSnapshot> VMSnapshotFromSettings(
       const Settings& settings);
 
+  //----------------------------------------------------------------------------
+  /// @brief      From the fields present in the given settings object, infer
+  ///             the isolate snapshot.
+  ///
+  /// @attention  Depending on the runtime mode of the Flutter application and
+  ///             the target that Flutter is running on, a complex fallback
+  ///             mechanism is in place to infer the locations of each snapshot
+  ///             buffer. If the caller wants to explicitly specify the buffers
+  ///             of the isolate snapshot, the `Settings::isolate_snapshot_data`
+  ///             and `Settings::isolate_snapshots_instr` mapping fields may be
+  ///             used. This specification takes precedence over all fallback
+  ///             search paths.
+  ///
+  /// @param[in]  settings  The settings to infer the isolate snapshot from.
+  ///
+  /// @return     A valid isolate snapshot or nullptr.
+  ///
   static fml::RefPtr<DartSnapshot> IsolateSnapshotFromSettings(
       const Settings& settings);
 
+  //----------------------------------------------------------------------------
+  /// @brief      An empty an invalid snapshot. This is used as a placeholder
+  ///             for certain optional snapshots.
+  ///
+  /// @bug        Now that shared snapshots are no longer required, consider
+  ///             removing this constructor.
+  ///
+  /// @return     An invalid empty snapshot.
+  ///
   static fml::RefPtr<DartSnapshot> Empty();
 
+  //----------------------------------------------------------------------------
+  /// @brief      Determines if this snapshot contains a heap component. Since
+  ///             the instructions component is optional, the method does not
+  ///             check for its presence. Use `IsValidForAOT` to determine if
+  ///             both the heap and instructions components of the snapshot are
+  ///             present.
+  ///
+  /// @return     Returns if the snapshot contains a heap component.
+  ///
   bool IsValid() const;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Determines if this snapshot contains both the heap and
+  ///             instructions components. This is only useful when determining
+  ///             if the snapshot may be used to run AOT code. The instructions
+  ///             component will be absent in JIT modes.
+  ///
+  /// @return     Returns if the snapshot contains both a heap and instructions
+  ///             component.
+  ///
   bool IsValidForAOT() const;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Get a pointer to the read-only mapping to the heap snapshot.
+  ///
+  /// @return     The data mapping.
+  ///
   const uint8_t* GetDataMapping() const;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Get a pointer to the read-execute mapping to the instructions
+  ///             snapshot.
+  ///
+  /// @return     The instructions mapping.
+  ///
   const uint8_t* GetInstructionsMapping() const;
 
  private: