[various] Standardize Obj-C doc comment style (flutter#6232)

Standardizes Objective-C code on `///` for documentation comments, instead of a mix of that and `/** ... */`.

This does not add enforcement, since my expectation is that if we start from a homogeneous style we will be much less likely to diverge again (and if some do creep in, it's harmless).

This only changes comments, so is a no-op for package clients.

Fixes flutter/flutter#143868

Author: stuartmorgan-g

packages/camera/camera_avfoundation/ios/Classes/CameraProperties.h

@@ -9,9 +9,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - flash mode
 
-/**
- * Represents camera's flash mode. Mirrors `FlashMode` enum in flash_mode.dart.
- */
+/// Represents camera's flash mode. Mirrors `FlashMode` enum in flash_mode.dart.
 typedef NS_ENUM(NSInteger, FLTFlashMode) {
   FLTFlashModeOff,
   FLTFlashModeAuto,
@@ -22,23 +20,17 @@ typedef NS_ENUM(NSInteger, FLTFlashMode) {
   FLTFlashModeInvalid,
 };
 
-/**
- * Gets FLTFlashMode from its string representation.
- * @param mode a string representation of the FLTFlashMode.
- */
+/// Gets FLTFlashMode from its string representation.
+/// @param mode a string representation of the FLTFlashMode.
 extern FLTFlashMode FLTGetFLTFlashModeForString(NSString *mode);
 
-/**
- * Gets AVCaptureFlashMode from FLTFlashMode.
- * @param mode flash mode.
- */
+/// Gets AVCaptureFlashMode from FLTFlashMode.
+/// @param mode flash mode.
 extern AVCaptureFlashMode FLTGetAVCaptureFlashModeForFLTFlashMode(FLTFlashMode mode);
 
 #pragma mark - exposure mode
 
-/**
- * Represents camera's exposure mode. Mirrors ExposureMode in camera.dart.
- */
+/// Represents camera's exposure mode. Mirrors ExposureMode in camera.dart.
 typedef NS_ENUM(NSInteger, FLTExposureMode) {
   FLTExposureModeAuto,
   FLTExposureModeLocked,
@@ -47,23 +39,17 @@ typedef NS_ENUM(NSInteger, FLTExposureMode) {
   FLTExposureModeInvalid,
 };
 
-/**
- * Gets a string representation of exposure mode.
- * @param mode exposure mode
- */
+/// Gets a string representation of exposure mode.
+/// @param mode exposure mode
 extern NSString *FLTGetStringForFLTExposureMode(FLTExposureMode mode);
 
-/**
- * Gets FLTExposureMode from its string representation.
- * @param mode a string representation of the FLTExposureMode.
- */
+/// Gets FLTExposureMode from its string representation.
+/// @param mode a string representation of the FLTExposureMode.
 extern FLTExposureMode FLTGetFLTExposureModeForString(NSString *mode);
 
 #pragma mark - focus mode
 
-/**
- * Represents camera's focus mode. Mirrors FocusMode in camera.dart.
- */
+/// Represents camera's focus mode. Mirrors FocusMode in camera.dart.
 typedef NS_ENUM(NSInteger, FLTFocusMode) {
   FLTFocusModeAuto,
   FLTFocusModeLocked,
@@ -72,35 +58,25 @@ typedef NS_ENUM(NSInteger, FLTFocusMode) {
   FLTFocusModeInvalid,
 };
 
-/**
- * Gets a string representation from FLTFocusMode.
- * @param mode focus mode
- */
+/// Gets a string representation from FLTFocusMode.
+/// @param mode focus mode
 extern NSString *FLTGetStringForFLTFocusMode(FLTFocusMode mode);
 
-/**
- * Gets FLTFocusMode from its string representation.
- * @param mode a string representation of focus mode.
- */
+/// Gets FLTFocusMode from its string representation.
+/// @param mode a string representation of focus mode.
 extern FLTFocusMode FLTGetFLTFocusModeForString(NSString *mode);
 
 #pragma mark - device orientation
 
-/**
- * Gets UIDeviceOrientation from its string representation.
- */
+/// Gets UIDeviceOrientation from its string representation.
 extern UIDeviceOrientation FLTGetUIDeviceOrientationForString(NSString *orientation);
 
-/**
- * Gets a string representation of UIDeviceOrientation.
- */
+/// Gets a string representation of UIDeviceOrientation.
 extern NSString *FLTGetStringForUIDeviceOrientation(UIDeviceOrientation orientation);
 
 #pragma mark - resolution preset
 
-/**
- * Represents camera's resolution present. Mirrors ResolutionPreset in camera.dart.
- */
+/// Represents camera's resolution present. Mirrors ResolutionPreset in camera.dart.
 typedef NS_ENUM(NSInteger, FLTResolutionPreset) {
   FLTResolutionPresetVeryLow,
   FLTResolutionPresetLow,
@@ -114,22 +90,16 @@ typedef NS_ENUM(NSInteger, FLTResolutionPreset) {
   FLTResolutionPresetInvalid,
 };
 
-/**
- * Gets FLTResolutionPreset from its string representation.
- * @param preset a string representation of FLTResolutionPreset.
- */
+/// Gets FLTResolutionPreset from its string representation.
+/// @param preset a string representation of FLTResolutionPreset.
 extern FLTResolutionPreset FLTGetFLTResolutionPresetForString(NSString *preset);
 
 #pragma mark - video format
 
-/**
- * Gets VideoFormat from its string representation.
- */
+/// Gets VideoFormat from its string representation.
 extern OSType FLTGetVideoFormatFromString(NSString *videoFormatString);
 
-/**
- * Represents image format. Mirrors ImageFileFormat in camera.dart.
- */
+/// Represents image format. Mirrors ImageFileFormat in camera.dart.
 typedef NS_ENUM(NSInteger, FCPFileFormat) {
   FCPFileFormatJPEG,
   FCPFileFormatHEIF,
@@ -138,9 +108,7 @@ typedef NS_ENUM(NSInteger, FCPFileFormat) {
 
 #pragma mark - image extension
 
-/**
- * Gets a string representation of ImageFileFormat.
- */
+/// Gets a string representation of ImageFileFormat.
 extern FCPFileFormat FCPGetFileFormatFromString(NSString *fileFormatString);
 
 NS_ASSUME_NONNULL_END

packages/camera/camera_avfoundation/ios/Classes/FLTCam.h

@@ -14,9 +14,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- * A class that manages camera's state and performs camera operations.
- */
+/// A class that manages camera's state and performs camera operations.
 @interface FLTCam : NSObject <FlutterTexture>
 
 @property(readonly, nonatomic) AVCaptureDevice *captureDevice;
@@ -52,13 +50,11 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)close;
 - (void)startVideoRecordingWithResult:(FLTThreadSafeFlutterResult *)result;
 - (void)setImageFileFormat:(FCPFileFormat)fileFormat;
-/**
- * Starts recording a video with an optional streaming messenger.
- * If the messenger is non-null then it will be called for each
- * captured frame, allowing streaming concurrently with recording.
- *
- * @param messenger Nullable messenger for capturing each frame.
- */
+/// Starts recording a video with an optional streaming messenger.
+/// If the messenger is non-null then it will be called for each
+/// captured frame, allowing streaming concurrently with recording.
+///
+/// @param messenger Nullable messenger for capturing each frame.
 - (void)startVideoRecordingWithResult:(FLTThreadSafeFlutterResult *)result
                 messengerForStreaming:(nullable NSObject<FlutterBinaryMessenger> *)messenger;
 - (void)stopVideoRecordingWithResult:(FLTThreadSafeFlutterResult *)result;
@@ -72,28 +68,24 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)setFocusModeWithResult:(FLTThreadSafeFlutterResult *)result mode:(NSString *)modeStr;
 - (void)applyFocusMode;
 
-/**
- * Acknowledges the receipt of one image stream frame.
- *
- * This should be called each time a frame is received. Failing to call it may
- * cause later frames to be dropped instead of streamed.
- */
+/// Acknowledges the receipt of one image stream frame.
+///
+/// This should be called each time a frame is received. Failing to call it may
+/// cause later frames to be dropped instead of streamed.
 - (void)receivedImageStreamData;
 
-/**
- * Applies FocusMode on the AVCaptureDevice.
- *
- * If the @c focusMode is set to FocusModeAuto the AVCaptureDevice is configured to use
- * AVCaptureFocusModeContinuousModeAutoFocus when supported, otherwise it is set to
- * AVCaptureFocusModeAutoFocus. If neither AVCaptureFocusModeContinuousModeAutoFocus nor
- * AVCaptureFocusModeAutoFocus are supported focus mode will not be set.
- * If @c focusMode is set to FocusModeLocked the AVCaptureDevice is configured to use
- * AVCaptureFocusModeAutoFocus. If AVCaptureFocusModeAutoFocus is not supported focus mode will not
- * be set.
- *
- * @param focusMode The focus mode that should be applied to the @captureDevice instance.
- * @param captureDevice The AVCaptureDevice to which the @focusMode will be applied.
- */
+/// Applies FocusMode on the AVCaptureDevice.
+///
+/// If the @c focusMode is set to FocusModeAuto the AVCaptureDevice is configured to use
+/// AVCaptureFocusModeContinuousModeAutoFocus when supported, otherwise it is set to
+/// AVCaptureFocusModeAutoFocus. If neither AVCaptureFocusModeContinuousModeAutoFocus nor
+/// AVCaptureFocusModeAutoFocus are supported focus mode will not be set.
+/// If @c focusMode is set to FocusModeLocked the AVCaptureDevice is configured to use
+/// AVCaptureFocusModeAutoFocus. If AVCaptureFocusModeAutoFocus is not supported focus mode will not
+/// be set.
+///
+/// @param focusMode The focus mode that should be applied to the @captureDevice instance.
+/// @param captureDevice The AVCaptureDevice to which the @focusMode will be applied.
 - (void)applyFocusMode:(FLTFocusMode)focusMode onDevice:(AVCaptureDevice *)captureDevice;
 - (void)pausePreviewWithResult:(FLTThreadSafeFlutterResult *)result;
 - (void)resumePreviewWithResult:(FLTThreadSafeFlutterResult *)result;

packages/camera/camera_avfoundation/ios/Classes/FLTSavePhotoDelegate.h

@@ -18,18 +18,14 @@ NS_ASSUME_NONNULL_BEGIN
 typedef void (^FLTSavePhotoDelegateCompletionHandler)(NSString *_Nullable path,
                                                       NSError *_Nullable error);
 
-/**
- Delegate object that handles photo capture results.
- */
+/// Delegate object that handles photo capture results.
 @interface FLTSavePhotoDelegate : NSObject <AVCapturePhotoCaptureDelegate>
 
-/**
- * Initialize a photo capture delegate.
- * @param path the path for captured photo file.
- * @param ioQueue the queue on which captured photos are written to disk.
- * @param completionHandler The completion handler block for save photo operations. Can
- * be called from either main queue or IO queue.
- */
+/// Initialize a photo capture delegate.
+/// @param path the path for captured photo file.
+/// @param ioQueue the queue on which captured photos are written to disk.
+/// @param completionHandler The completion handler block for save photo operations. Can
+/// be called from either main queue or IO queue.
 - (instancetype)initWithPath:(NSString *)path
                      ioQueue:(dispatch_queue_t)ioQueue
            completionHandler:(FLTSavePhotoDelegateCompletionHandler)completionHandler;

packages/camera/camera_avfoundation/ios/Classes/FLTSavePhotoDelegate_Test.h

@@ -4,9 +4,7 @@
 
 #import "FLTSavePhotoDelegate.h"
 
-/**
- API exposed for unit tests.
- */
+/// API exposed for unit tests.
 @interface FLTSavePhotoDelegate ()
 
 /// The completion handler block for capture and save photo operations.

packages/camera/camera_avfoundation/ios/Classes/FLTThreadSafeEventChannel.h

@@ -6,22 +6,16 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- * A thread safe wrapper for FlutterEventChannel that can be called from any thread, by dispatching
- * its underlying engine calls to the main thread.
- */
+/// A thread safe wrapper for FlutterEventChannel that can be called from any thread, by dispatching
+/// its underlying engine calls to the main thread.
 @interface FLTThreadSafeEventChannel : NSObject
 
-/**
- * Creates a FLTThreadSafeEventChannel by wrapping a FlutterEventChannel object.
- * @param channel The FlutterEventChannel object to be wrapped.
- */
+/// Creates a FLTThreadSafeEventChannel by wrapping a FlutterEventChannel object.
+/// @param channel The FlutterEventChannel object to be wrapped.
 - (instancetype)initWithEventChannel:(FlutterEventChannel *)channel;
 
-/*
- * Registers a handler on the main thread for stream setup requests from the Flutter side.
- # The completion block runs on the main thread.
- */
+/// Registers a handler on the main thread for stream setup requests from the Flutter side.
+/// The completion block runs on the main thread.
 - (void)setStreamHandler:(nullable NSObject<FlutterStreamHandler> *)handler
               completion:(void (^)(void))completion;
 

packages/camera/camera_avfoundation/ios/Classes/FLTThreadSafeFlutterResult.h

@@ -6,56 +6,38 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- * A thread safe wrapper for FlutterResult that can be called from any thread, by dispatching its
- * underlying engine calls to the main thread.
- */
+/// A thread safe wrapper for FlutterResult that can be called from any thread, by dispatching its
+/// underlying engine calls to the main thread.
 @interface FLTThreadSafeFlutterResult : NSObject
 
-/**
- * Gets the original FlutterResult object wrapped by this FLTThreadSafeFlutterResult instance.
- */
+/// Gets the original FlutterResult object wrapped by this FLTThreadSafeFlutterResult instance.
 @property(readonly, nonatomic) FlutterResult flutterResult;
 
-/**
- * Initializes with a FlutterResult object.
- * @param result The FlutterResult object that the result will be given to.
- */
+/// Initializes with a FlutterResult object.
+/// @param result The FlutterResult object that the result will be given to.
 - (instancetype)initWithResult:(FlutterResult)result;
 
-/**
- * Sends a successful result on the main thread without any data.
- */
+/// Sends a successful result on the main thread without any data.
 - (void)sendSuccess;
 
-/**
- * Sends a successful result on the main thread with data.
- * @param data Result data that is send to the Flutter Dart side.
- */
+/// Sends a successful result on the main thread with data.
+/// @param data Result data that is send to the Flutter Dart side.
 - (void)sendSuccessWithData:(id)data;
 
-/**
- * Sends an NSError as result on the main thread.
- * @param error Error that will be send as FlutterError.
- */
+/// Sends an NSError as result on the main thread.
+/// @param error Error that will be send as FlutterError.
 - (void)sendError:(NSError *)error;
 
-/**
- * Sends a FlutterError as result on the main thread.
- * @param flutterError FlutterError that will be sent to the Flutter Dart side.
- */
+/// Sends a FlutterError as result on the main thread.
+/// @param flutterError FlutterError that will be sent to the Flutter Dart side.
 - (void)sendFlutterError:(FlutterError *)flutterError;
 
-/**
- * Sends a FlutterError as result on the main thread.
- */
+/// Sends a FlutterError as result on the main thread.
 - (void)sendErrorWithCode:(NSString *)code
                   message:(nullable NSString *)message
                   details:(nullable id)details;
 
-/**
- * Sends FlutterMethodNotImplemented as result on the main thread.
- */
+/// Sends FlutterMethodNotImplemented as result on the main thread.
 - (void)sendNotImplemented;
 @end
 

packages/camera/camera_avfoundation/ios/Classes/FLTThreadSafeFlutterResult.m

@@ -47,9 +47,7 @@ - (void)sendNotImplemented {
   [self send:FlutterMethodNotImplemented];
 }
 
-/**
- * Sends result to flutterResult on the main thread.
- */
+/// Sends result to flutterResult on the main thread.
 - (void)send:(id _Nullable)result {
   FLTEnsureToRunOnMainQueue(^{
     // WARNING: Should not use weak self, because `FlutterResult`s are passed as arguments

packages/camera/camera_avfoundation/ios/Classes/FLTThreadSafeMethodChannel.h

@@ -6,21 +6,15 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- * A thread safe wrapper for FlutterMethodChannel that can be called from any thread, by dispatching
- * its underlying engine calls to the main thread.
- */
+/// A thread safe wrapper for FlutterMethodChannel that can be called from any thread, by
+/// dispatching its underlying engine calls to the main thread.
 @interface FLTThreadSafeMethodChannel : NSObject
 
-/**
- * Creates a FLTThreadSafeMethodChannel by wrapping a FlutterMethodChannel object.
- * @param channel The FlutterMethodChannel object to be wrapped.
- */
+/// Creates a FLTThreadSafeMethodChannel by wrapping a FlutterMethodChannel object.
+/// @param channel The FlutterMethodChannel object to be wrapped.
 - (instancetype)initWithMethodChannel:(FlutterMethodChannel *)channel;
 
-/**
- * Invokes the specified flutter method on the main thread with the specified arguments.
- */
+/// Invokes the specified flutter method on the main thread with the specified arguments.
 - (void)invokeMethod:(NSString *)method arguments:(nullable id)arguments;
 
 @end