Applied feedback from PR

packages/camera/camera/android/src/main/java/io/flutter/plugins/camera/CameraProperties.java

@@ -16,40 +16,224 @@
 
 /** An interface allowing access to the different characteristics of the device's camera. */
 public interface CameraProperties {
+
+  /**
+   * Returns the name (or identifier) of the camera device.
+   *
+   * @return String The name of the camera device.
+   */
   String getCameraName();
 
+  /**
+   * Returns the list of frame rate ranges for @see android.control.aeTargetFpsRange supported by
+   * this camera device.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_AE_TARGET_FPS_RANGE key.
+   *
+   * @return android.util.Range<Integer>[] List of frame rate ranges supported by this camera
+   *     device.
+   */
   Range<Integer>[] getControlAutoExposureAvailableTargetFpsRanges();
 
+  /**
+   * Returns the maximum and minimum exposure compensation values for @see
+   * android.control.aeExposureCompensation, in counts of @see android.control.aeCompensationStep,
+   * that are supported by this camera device.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE key.
+   *
+   * @return android.util.Range<Integer> Maximum and minimum exposure compensation supported by this
+   *     camera device.
+   */
   Range<Integer> getControlAutoExposureCompensationRange();
 
+  /**
+   * Returns the smallest step by which the exposure compensation can be changed.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP key.
+   *
+   * @return double Smallest step by which the exposure compensation can be changed.
+   */
   double getControlAutoExposureCompensationStep();
 
+  /**
+   * Returns a list of auto-focus modes for @see android.control.afMode that are supported by this
+   * camera device.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES key.
+   *
+   * @return int[] List of auto-focus modes supported by this camera device.
+   */
   int[] getControlAutoFocusAvailableModes();
 
+  /**
+   * Returns the maximum number of metering regions that can be used by the auto-exposure routine.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_MAX_REGIONS_AE key.
+   *
+   * @return Integer Maximum number of metering regions that can be used by the auto-exposure
+   *     routine.
+   */
   Integer getControlMaxRegionsAutoExposure();
 
+  /**
+   * Returns the maximum number of metering regions that can be used by the auto-focus routine.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#CONTROL_MAX_REGIONS_AF key.
+   *
+   * @return Integer Maximum number of metering regions that can be used by the auto-focus routine.
+   */
   Integer getControlMaxRegionsAutoFocus();
 
+  /**
+   * Returns a list of distortion correction modes for @see android.distortionCorrection.mode that
+   * are supported by this camera device.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#DISTORTION_CORRECTION_AVAILABLE_MODES key.
+   *
+   * @return int[] List of distortion correction modes supported by this camera device.
+   */
+  @RequiresApi(api = VERSION_CODES.P)
   int[] getDistortionCorrectionAvailableModes();
 
+  /**
+   * Returns whether this camera device has a flash unit.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#FLASH_INFO_AVAILABLE key.
+   *
+   * @return Boolean Whether this camera device has a flash unit.
+   */
   Boolean getFlashInfoAvailable();
 
+  /**
+   * Returns the direction the camera faces relative to device screen.
+   *
+   * <p><string>Possible values:</string>
+   *
+   * <ul>
+   *   <li>@see android.hardware.camera2.CameraMetadata.LENS_FACING_FRONT
+   *   <li>@see android.hardware.camera2.CameraMetadata.LENS_FACING_BACK
+   *   <li>@see android.hardware.camera2.CameraMetadata.LENS_FACING_EXTERNAL
+   * </ul>
+   *
+   * By default maps to the @see android.hardware.camera2.CameraCharacteristics.LENS_FACING key.
+   *
+   * @return int Direction the camera faces relative to device screen.
+   */
   int getLensFacing();
 
+  /**
+   * Returns the shortest distance from front most surface of the lens that can be brought into
+   * sharp focus.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE key.
+   *
+   * @return Float Shortest distance from front most surface of the lens that can be brought into
+   *     sharp focus.
+   */
   Float getLensInfoMinimumFocusDistance();
 
+  /**
+   * Returns the maximum ratio between both active area width and crop region width, and active area
+   * height and crop region height, for @see android.scaler.cropRegion.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM key.
+   *
+   * @return Float Maximum ratio between both active area width and crop region width, and active
+   *     area height and crop region height
+   */
   Float getScalerAvailableMaxDigitalZoom();
 
+  /**
+   * Returns the area of the image sensor which corresponds to active pixels after any geometric
+   * distortion correction has been applied.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE key.
+   *
+   * @return android.graphics.Rect area of the image sensor which corresponds to active pixels after
+   *     any geometric distortion correction has been applied.
+   */
   Rect getSensorInfoActiveArraySize();
 
+  /**
+   * Returns the dimensions of the full pixel array, possibly including black calibration pixels.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE key.
+   *
+   * @return android.util.Size Dimensions of the full pixel array, possibly including black
+   *     calibration pixels.
+   */
   Size getSensorInfoPixelArraySize();
 
+  /**
+   * Returns the area of the image sensor which corresponds to active pixels prior to the
+   * application of any geometric distortion correction.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE
+   * key.
+   *
+   * @return android.graphics.Rect Area of the image sensor which corresponds to active pixels prior
+   *     to the application of any geometric distortion correction.
+   */
+  @RequiresApi(api = VERSION_CODES.M)
   Rect getSensorInfoPreCorrectionActiveArraySize();
 
+  /**
+   * Returns the clockwise angle through which the output image needs to be rotated to be upright on
+   * the device screen in its native orientation.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#SENSOR_ORIENTATION key.
+   *
+   * @return int Clockwise angle through which the output image needs to be rotated to be upright on
+   *     the device screen in its native orientation.
+   */
   int getSensorOrientation();
 
+  /**
+   * Returns a level which generally classifies the overall set of the camera device functionality.
+   *
+   * <p><strong>Possible values:</strong>
+   *
+   * <ul>
+   *   <li>@see android.hardware.camera2.CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY
+   *   <li>@see android.hardware.camera2.CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED
+   *   <li>@see android.hardware.camera2.CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_FULL
+   *   <li>@see android.hardware.camera2.CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LEVEL_3
+   *   <li>@see android.hardware.camera2.CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
+   * </ul>
+   *
+   * By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL key.
+   *
+   * @return int Level which generally classifies the overall set of the camera device
+   *     functionality.
+   */
   int getHardwareLevel();
 
+  /**
+   * Returns a list of noise reduction modes for @see android.noiseReduction.mode that are supported
+   * by this camera device.
+   *
+   * <p>By default maps to the @see
+   * android.hardware.camera2.CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
+   * key.
+   *
+   * @return int[] List of noise reduction modes that are supported by this camera device.
+   */
   int[] getAvailableNoiseReductionModes();
 }
 

packages/camera/camera/android/src/main/java/io/flutter/plugins/camera/features/CameraFeature.java

@@ -27,30 +27,33 @@ protected CameraFeature(@NonNull CameraProperties cameraProperties) {
   public abstract String getDebugName();
 
   /**
-   * Get the current value of this feature's setting.
+   * Gets the current value of this feature's setting.
    *
-   * @return
+   * @return <T> Current value of this feature's setting.
    */
   public abstract T getValue();
 
   /**
-   * Set a new value for this feature's setting.
+   * Sets a new value for this feature's setting.
    *
-   * @param value
+   * @param value New value for this feature's setting.
    */
   public abstract void setValue(T value);
 
   /**
    * Returns whether or not this feature is supported.
    *
-   * @return
+   * <p>When the feature is not supported any {@see #value} is simply ignored by the camera plugin.
+   *
+   * @return boolean Whether or not this feature is supported.
    */
   public abstract boolean checkIsSupported();
 
   /**
-   * Update the setting in a provided request builder.
+   * Updates the setting in a provided {@see android.hardware.camera2.CaptureRequest.Builder}.
    *
-   * @param requestBuilder
+   * @param requestBuilder A {@see android.hardware.camera2.CaptureRequest.Builder} instance used to
+   *     configure the settings and outputs needed to capture a single image from the camera device.
    */
   public abstract void updateBuilder(CaptureRequest.Builder requestBuilder);
 }