Add some important comments to some of the FilteContents methods

impeller/entity/contents/filters/filter_contents.h

@@ -132,17 +132,36 @@ class FilterContents : public Contents {
   // |Contents|
   const FilterContents* AsFilter() const override;
 
-  /// @brief Determines the coverage of source pixels that will be needed
-  ///        to apply this filter under the given transform and produce
-  ///        results anywhere within the indicated coverage limit.
+  /// @brief  Determines the coverage of source pixels that will be needed
+  ///         to produce results for the specified |output_limit| under the
+  ///         specified |effect_transform|. This is essentially a reverse of
+  ///         the |GetCoverage| method computing a source coverage from
+  ///         an intended |output_limit| coverage.
   ///
-  ///        This is useful for subpass rendering scenarios where a filter
-  ///        will be applied to the output of the subpass and we need to
-  ///        determine how large of a render target to allocate in order
-  ///        to collect all pixels that might affect the supplied output
-  ///        coverage limit. While we might clip the rendering of the subpass,
-  ///        we want to avoid clipping out any pixels that contribute to
-  ///        the output limit via the filtering operation.
+  ///         Both the |output_limit| and the return value are in the
+  ///         transformed coordinate space, and so do not need to be
+  ///         transformed or inverse transformed by the |effect_transform|
+  ///         but individual parameters on the filter might be in the
+  ///         untransformed space and should be transformed by the
+  ///         |effect_transform| before applying them to the coverages.
+  ///
+  ///         The method computes a result such that if the filter is applied
+  ///         to a set of pixels filling the computed source coverage, it
+  ///         should produce an output that covers the entire specified
+  ///         |output_limit|.
+  ///
+  ///         This is useful for subpass rendering scenarios where a filter
+  ///         will be applied to the output of the subpass and we need to
+  ///         determine how large of a render target to allocate in order
+  ///         to collect all pixels that might affect the supplied output
+  ///         coverage limit. While we might end up clipping the rendering
+  ///         of the subpass to its destination, we want to avoid clipping
+  ///         out any pixels that contribute to the output limit via the
+  ///         filtering operation.
+  ///
+  /// @return The coverage bounds in the transformed space of any source pixel
+  ///         that may be needed to produce output for the indicated filter
+  ///         that covers the indicated |output_limit|.
   std::optional<Rect> GetSourceCoverage(const Matrix& effect_transform,
                                         const Rect& output_limit) const;
 
@@ -178,11 +197,18 @@ class FilterContents : public Contents {
   virtual void SetRenderingMode(Entity::RenderingMode rendering_mode);
 
  private:
+  /// @brief  Internal utility method for |GetLocalCoverage| that computes
+  ///         the output coverage of this filter across the specified inputs,
+  ///         ignoring the coverage hint.
   virtual std::optional<Rect> GetFilterCoverage(
       const FilterInput::Vector& inputs,
       const Entity& entity,
       const Matrix& effect_transform) const;
 
+  /// @brief  Internal utility method for |GetSourceCoverage| that computes
+  ///         the inverse effect of this transform on the specified output
+  ///         coverage, ignoring the inputs which will be accommodated by
+  ///         the caller.
   virtual std::optional<Rect> GetFilterSourceCoverage(
       const Matrix& effect_transform,
       const Rect& output_limit) const = 0;
@@ -196,6 +222,11 @@ class FilterContents : public Contents {
       const Rect& coverage,
       const std::optional<Rect>& coverage_hint) const = 0;
 
+  /// @brief  Internal utility method to compute the coverage of this
+  ///         filter across its internally specified inputs and subject
+  ///         to the coverage hint.
+  ///
+  ///         Uses |GetFilterCoverage|.
   std::optional<Rect> GetLocalCoverage(const Entity& local_entity) const;
 
   FilterInput::Vector inputs_;