adds Entity docstrings (#167228)

fixes https://github.com/flutter/flutter/issues/144943

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

engine/src/flutter/impeller/entity/entity.h

@@ -17,6 +17,12 @@ namespace impeller {
 class Renderer;
 class RenderPass;
 
+/// Represents a renderable object within the Impeller scene.
+///
+/// An Entity combines graphical content (`Contents`) with properties
+/// like transformation (`Matrix`), blend mode (`BlendMode`), and stencil
+/// clip depth. It serves as the primary unit for constructing and rendering
+/// scenes. Entities can be created directly or from `Snapshot` objects.
 class Entity {
  public:
   static constexpr BlendMode kLastPipelineBlendMode = BlendMode::kModulate;
@@ -78,7 +84,14 @@ class Entity {
   /// @brief  Get the global transform matrix for this Entity.
   const Matrix& GetTransform() const;
 
-  /// @brief  Get the vertex shader transform used for drawing this Entity.
+  /// Calculates the final transformation matrix for rendering in a shader.
+  ///
+  /// This combines the entity's transform with the render pass's orthographic
+  /// projection and applies the necessary adjustments based on the entity's
+  /// shader clip depth.
+  ///
+  /// @param[in] pass The current render pass.
+  /// @return The combined model-view-projection matrix for the shader.
   Matrix GetShaderTransform(const RenderPass& pass) const;
 
   /// @brief  Static utility that computes the vertex shader transform used for
@@ -90,18 +103,56 @@ class Entity {
   /// @brief  Set the global transform matrix for this Entity.
   void SetTransform(const Matrix& transform);
 
+  /// Calculates the axis-aligned bounding box covering this entity after its
+  /// transformation is applied.
+  /// @return The coverage rectangle in the parent coordinate space, or
+  /// `std::nullopt` if the entity has no contents.
   std::optional<Rect> GetCoverage() const;
 
   void SetContents(std::shared_ptr<Contents> contents);
 
   const std::shared_ptr<Contents>& GetContents() const;
 
+  /// Sets the stencil clip depth for this entity.
+  ///
+  /// The clip depth determines the entity's level within a stack of stencil
+  /// clips. Higher values indicate the entity is nested deeper within clips.
+  /// This value is used during rendering to configure stencil buffer
+  /// operations.
+  ///
+  /// @param[in] clip_depth The integer clip depth level.
   void SetClipDepth(uint32_t clip_depth);
 
+  /// Gets the stencil clip depth level for this entity.
+  ///
+  /// @see SetClipDepth(uint32_t)
+  /// @see GetShaderClipDepth()
+  ///
+  /// @return The current integer clip depth level.
   uint32_t GetClipDepth() const;
 
+  /// Gets the shader-compatible depth value based on the entity's current clip
+  /// depth level (`clip_depth_`).
+  ///
+  /// @see GetShaderClipDepth(uint32_t) for details on the conversion logic.
+  ///
+  /// @return The floating-point depth value for shaders corresponding to the
+  /// entity's `clip_depth_`.
   float GetShaderClipDepth() const;
 
+  /// Converts an integer clip depth level into a floating-point depth value
+  /// suitable for use in shaders.
+  ///
+  /// The integer `clip_depth` represents discrete layers used for stencil
+  /// clipping. This function maps that integer to a depth value within the [0,
+  /// 1) range for the depth buffer. Each increment in `clip_depth` corresponds
+  /// to a small step (`kDepthEpsilon`) in the shader depth.
+  ///
+  /// The result is clamped to ensure it stays within the valid depth range and
+  /// slightly below 1.0 to avoid potential issues with the maximum depth value.
+  ///
+  /// @param[in] clip_depth The integer clip depth level.
+  /// @return The corresponding floating-point depth value for shaders.
   static float GetShaderClipDepth(uint32_t clip_depth);
 
   void SetBlendMode(BlendMode blend_mode);
@@ -114,6 +165,14 @@ class Entity {
 
   bool SetInheritedOpacity(Scalar alpha);
 
+  /// Attempts to represent this entity as a solid background color.
+  ///
+  /// This is an optimization. If the entity's contents can be represented as a
+  /// solid color covering the entire target area, this method returns that
+  /// color.
+  ///
+  /// @param[in] target_size The size of the render target.
+  /// @return The background color if representable, otherwise `std::nullopt`.
   std::optional<Color> AsBackgroundColor(ISize target_size) const;
 
   Entity Clone() const;