Add docs

packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/DeviceOrientationManager.java

@@ -48,13 +48,12 @@ interface DeviceOrientationChangeCallback {
     this.deviceOrientationChangeCallback = callback;
   }
 
-  // TODO(camsim99): Fix docs.
   /**
    * Starts listening to the device's sensors or UI for orientation updates.
    *
-   * <p>When orientation information is updated the new orientation is send to the client using the
-   * {@link DartMessenger}. This latest value can also be retrieved through the {@link
-   * #getVideoOrientation()} accessor.
+   * <p>When orientation information is updated, the callback method of the {@link
+   * DeviceOrientationChangeCallback} is called with the new orientation. This latest value can also
+   * be retrieved through the {@link #getVideoOrientation()} accessor.
    *
    * <p>If the device's ACCELEROMETER_ROTATION setting is enabled the {@link
    * DeviceOrientationManager} will report orientation updates based on the sensor information. If

packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/SystemServicesHostApiImpl.java

@@ -39,6 +39,12 @@ public void setPermissionsRegistry(PermissionsRegistry permissionsRegistry) {
     this.permissionsRegistry = permissionsRegistry;
   }
 
+  /**
+   * Requests camera permissions using an instance of a {@link CameraPermissionsManager}.
+   *
+   * <p>Will result with {@code null} if permissions were approved or there were no errors;
+   * otherwise, it will result with the error data explaining what went wrong.
+   */
   @Override
   public void requestCameraPermissions(
       Boolean enableAudio, Result<CameraPermissionsErrorData> result) {
@@ -63,6 +69,13 @@ public void requestCameraPermissions(
         });
   }
 
+  /**
+   * Starts listening for device orientation changes using an instace of a {@link
+   * DeviceOrientationManager}.
+   *
+   * <p>Whenever a change in device orientation is detected by the {@code DeviceOrientationManager},
+   * the {@link SystemServicesFlutterApi} will be used to notify the Dart side.
+   */
   @Override
   public void startListeningForDeviceOrientationChange(
       Boolean isFrontFacing, Long sensorOrientation) {

packages/camera/camera_android_camerax/lib/src/instance_manager.dart

@@ -124,22 +124,26 @@ class InstanceManager {
   /// This method also expects the host `InstanceManager` to have a strong
   /// reference to the instance the identifier is associated with.
   T? getInstanceWithWeakReference<T extends Object>(int identifier) {
-    final Object? weakInstance = _weakInstances[identifier]?.target;
+    final T? weakInstance = _weakInstances[identifier]?.target as T?;
 
     if (weakInstance == null) {
-      final Object? strongInstance = _strongInstances[identifier];
+      final T? strongInstance = _strongInstances[identifier] as T?;
       if (strongInstance != null) {
-        final Object copy =
-            _copyCallbacks[identifier]!(strongInstance)! as Object;
+        // This cast is safe since it matches the argument type for
+        // _addInstanceWithIdentifier, which is the only place _copyCallbacks
+        // is populated.
+        final T Function(T) copyCallback =
+            _copyCallbacks[identifier]! as T Function(T);
+        final T copy = copyCallback(strongInstance);
         _identifiers[copy] = identifier;
-        _weakInstances[identifier] = WeakReference<Object>(copy);
+        _weakInstances[identifier] = WeakReference<T>(copy);
         _finalizer.attach(copy, identifier, detach: copy);
-        return copy as T;
+        return copy;
       }
-      return strongInstance as T?;
+      return strongInstance;
     }
 
-    return weakInstance as T;
+    return weakInstance;
   }
 
   /// Retrieves the identifier associated with instance.
@@ -152,7 +156,7 @@ class InstanceManager {
   /// In other words, the host platform wants to add a new instance that
   /// represents an object on the host platform. Stored with [identifier].
   ///
-  /// Throws assertion error if the instance has already been
+  /// Throws assertion error if the instance or its identifier has already been
   /// added.
   ///
   /// Returns unique identifier of the [instance] added.
@@ -161,6 +165,7 @@ class InstanceManager {
     int identifier, {
     required T Function(T original) onCopy,
   }) {
+    assert(!containsIdentifier(identifier));
     assert(getIdentifier(instance) == null);
     assert(identifier >= 0);
     _addInstanceWithIdentifier(instance, identifier, onCopy: onCopy);

packages/camera/camera_android_camerax/lib/src/system_services.dart

@@ -13,22 +13,28 @@ import 'camerax_library.pigeon.dart';
 import 'instance_manager.dart';
 import 'java_object.dart';
 
+/// Utility class that offers access to Android system services needed for
+/// camera usage.
 class SystemServices {
-  static final StreamController<bool> cameraPermissionsStreamController =
-      StreamController<bool>.broadcast();
-
+  /// Stream that emits the device orientation whenever it is changed/
+  ///
+  /// Values may start being added to the stream once
+  /// `startListeningForDeviceOrientationChange(...)` is called.
   static final StreamController<DeviceOrientationChangedEvent>
       deviceOrientationChangedStreamController =
       StreamController<DeviceOrientationChangedEvent>.broadcast();
 
+  /// Requests permission to access the camera and audio if specified.
   static Future<void> requestCameraPermissions(bool enableAudio,
       {BinaryMessenger? binaryMessenger}) {
     SystemServicesHostApiImpl api =
         SystemServicesHostApiImpl(binaryMessenger: binaryMessenger);
 
-    return api.requestCameraPermissionsFromInstance(enableAudio);
+    return api.requestCameraPermissions(enableAudio);
   }
 
+  /// Requests that [deviceOrientationChangedStreamController] start
+  /// emitting values for any change in device orientation.
   static void startListeningForDeviceOrientationChange(
       bool isFrontFacing, int sensorOrientation,
       {BinaryMessenger? binaryMessenger}) {
@@ -53,7 +59,11 @@ class SystemServicesHostApiImpl extends SystemServicesHostApi {
   /// the host platform.
   final BinaryMessenger? binaryMessenger;
 
-  Future<void> requestCameraPermissionsFromInstance(bool enableAudio) async {
+  /// Requests permission to access the camera and audio if specified.
+  ///
+  /// Will complete normally if permissions are successfully granted; otherwise,
+  /// will throw a [CameraException].
+  Future<void> requestCameraPermissions(bool enableAudio) async {
     CameraPermissionsErrorData? error =
         await requestCameraPermissions(enableAudio);