[ui] reland add docs to FragmentShader (flutter/engine#37699)

engine/src/flutter/lib/ui/painting.dart

@@ -4267,6 +4267,48 @@ class FragmentShader extends Shader {
   Float32List _floats = _kEmptyFloat32List;
 
   /// Sets the float uniform at [index] to [value].
+  ///
+  /// All uniforms defined in a fragment shader that are not samplers must be
+  /// set through this method. This includes floats and vec2, vec3, and vec4.
+  /// The correct index for each uniform is determined by the order of the
+  /// uniforms as defined in the fragment program, ignoring any samplers. For
+  /// data types that are composed of multiple floats such as a vec4, more than
+  /// one call to [setFloat] is required.
+  ///
+  /// For example, given the following uniforms in a fragment program:
+  ///
+  /// ```glsl
+  /// uniform float uScale;
+  /// uniform sampler2D uTexture;
+  /// uniform vec2 uMagnitude;
+  /// uniform vec4 uColor;
+  /// ```
+  ///
+  /// Then the corresponding Dart code to correctly initialize these uniforms
+  /// is:
+  ///
+  /// ```dart
+  /// void updateShader(ui.FragmentShader shader, Color color, ImageShader sampler) {
+  ///   shader.setFloat(0, 23);  // uScale
+  ///   shader.setFloat(1, 114); // uMagnitude x
+  ///   shader.setFloat(2, 83);  // uMagnitude y
+  ///
+  ///   // Convert color to premultiplied opacity.
+  ///   shader.setFloat(3, color.red / 255 * color.opacity);   // uColor r
+  ///   shader.setFloat(4, color.green / 255 * color.opacity); // uColor g
+  ///   shader.setFloat(5, color.blue / 255 * color.opacity);  // uColor b
+  ///   shader.setFloat(6, color.opacity);                     // uColor a
+  ///
+  ///   // initialize sampler uniform.
+  ///   shader.setSampler(0, sampler);
+  /// }
+  /// ```
+  ///
+  /// Note how the indexes used does not count the `sampler2D` uniform. This
+  /// uniform will be set separately with [setSampler], with the index starting
+  /// over at 0.
+  ///
+  /// Any float uniforms that are left uninitialized will default to `0`.
   void setFloat(int index, double value) {
     assert(!debugDisposed, 'Tried to accesss uniforms on a disposed Shader: $this');
     _floats[index] = value;
@@ -4274,6 +4316,9 @@ class FragmentShader extends Shader {
 
   /// Sets the sampler uniform at [index] to [sampler].
   ///
+  /// The index provided to setSampler is the index of the sampler uniform defined
+  /// in the fragment program, excluding all non-sampler uniforms.
+  ///
   /// All the sampler uniforms that a shader expects must be provided or the
   /// results will be undefined.
   void setSampler(int index, ImageShader sampler) {