Update Darwin availability annotations. (#31249)

* Update Darwin availability annotations.

In addition to updating the availability YAML:

* Introduces MTR_UNSTABLE_API and uses that for the metadata APIs, which are not ready to ship yet.
* Turns off MTR_PER_CONTROLLER_STORAGE_ENABLED for now.
* Updates availability on non-generated API bits.

* Address review comment

Author: bzbarsky-apple

src/darwin/Framework/CHIP/MTRCluster.h

@@ -44,20 +44,20 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * The endpoint this cluster lives on.
  */
-@property (nonatomic, readonly) NSNumber * endpointID NS_REFINED_FOR_SWIFT MTR_NEWLY_AVAILABLE;
+@property (nonatomic, readonly) NSNumber * endpointID NS_REFINED_FOR_SWIFT MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4));
 @end
 
 /**
  * Base for all MTRBaseCluster* types.
  */
-MTR_NEWLY_AVAILABLE
+MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4))
 @interface MTRGenericBaseCluster : MTRCluster
 @end
 
 /**
  * Base for all MTRCluster* types.
  */
-MTR_NEWLY_AVAILABLE
+MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4))
 @interface MTRGenericCluster : MTRCluster
 /**
  * The device this cluster object is associated with.

src/darwin/Framework/CHIP/MTRDefines.h

@@ -60,18 +60,30 @@
 
 #define MTR_NEWLY_AVAILABLE
 
+#define MTR_UNAVAILABLE NS_UNAVAILABLE MTR_HIDDEN
+
 #if !defined(MTR_ENABLE_PROVISIONAL)
 #define MTR_ENABLE_PROVISIONAL 0
 #endif
 
 #if MTR_ENABLE_PROVISIONAL
 #define MTR_PROVISIONALLY_AVAILABLE MTR_NEWLY_AVAILABLE
 #else
-#define MTR_PROVISIONALLY_AVAILABLE NS_UNAVAILABLE MTR_HIDDEN
+#define MTR_PROVISIONALLY_AVAILABLE MTR_UNAVAILABLE
+#endif
+
+#if !defined(MTR_ENABLE_UNSTABLE_API)
+#define MTR_ENABLE_UNSTABLE_API 0
+#endif
+
+#if MTR_ENABLE_UNSTABLE_API
+#define MTR_UNSTABLE_API MTR_NEWLY_AVAILABLE
+#else
+#define MTR_UNSTABLE_API MTR_UNAVAILABLE
 #endif
 
 #ifndef MTR_PER_CONTROLLER_STORAGE_ENABLED
-#define MTR_PER_CONTROLLER_STORAGE_ENABLED 1
+#define MTR_PER_CONTROLLER_STORAGE_ENABLED 0
 #endif
 
 #pragma mark - Types

src/darwin/Framework/CHIP/MTRDevice.h

@@ -81,12 +81,12 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * The controller this device was created for.  May return nil if that
  * controller has been shut down.
  */
-@property (nonatomic, readonly, nullable) MTRDeviceController * deviceController MTR_NEWLY_AVAILABLE;
+@property (nonatomic, readonly, nullable) MTRDeviceController * deviceController MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4));
 
 /**
  * The node ID of the node this device corresponds to.
  */
-@property (nonatomic, readonly, copy) NSNumber * nodeID NS_REFINED_FOR_SWIFT MTR_NEWLY_AVAILABLE;
+@property (nonatomic, readonly, copy) NSNumber * nodeID NS_REFINED_FOR_SWIFT MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4));
 
 /**
  * Set the delegate to receive asynchronous callbacks about the device.
@@ -189,7 +189,7 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
                      expectedValues:(NSArray<NSDictionary<NSString *, id> *> * _Nullable)expectedValues
               expectedValueInterval:(NSNumber * _Nullable)expectedValueInterval
                               queue:(dispatch_queue_t)queue
-                         completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
+                         completion:(MTRDeviceResponseHandler)completion MTR_AVAILABLE(ios(17.4), macos(14.4), watchos(10.4), tvos(17.4));
 
 - (void)invokeCommandWithEndpointID:(NSNumber *)endpointID
                           clusterID:(NSNumber *)clusterID
@@ -255,22 +255,22 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * List of all client data types supported
  *
  */
-- (NSArray *)supportedClientDataClasses MTR_NEWLY_AVAILABLE;
+- (NSArray *)supportedClientDataClasses MTR_UNSTABLE_API;
 
 /**
  *
  * List of all client data keys stored
  *
  */
-- (NSArray * _Nullable)clientDataKeys MTR_NEWLY_AVAILABLE;
+- (NSArray * _Nullable)clientDataKeys MTR_UNSTABLE_API;
 
 /**
  *
  * Retrieve client metadata for a key, returns nil if no value is set
  *
  * @param key           NSString * for the key to store the value as
  */
-- (id<NSSecureCoding> _Nullable)clientDataForKey:(NSString *)key MTR_NEWLY_AVAILABLE;
+- (id<NSSecureCoding> _Nullable)clientDataForKey:(NSString *)key MTR_UNSTABLE_API;
 
 /**
  *
@@ -279,22 +279,22 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * @param key           NSString * for the key to store the value as
  * @param value         id <NSSecureCoding> for the value to store
  */
-- (void)setClientDataForKey:(NSString *)key value:(id<NSSecureCoding>)value MTR_NEWLY_AVAILABLE;
+- (void)setClientDataForKey:(NSString *)key value:(id<NSSecureCoding>)value MTR_UNSTABLE_API;
 
 /**
  *
  * Remove client metadata for a key.
  *
  * @param key           NSString * for the key to store the value as
  */
-- (void)removeClientDataForKey:(NSString *)key MTR_NEWLY_AVAILABLE;
+- (void)removeClientDataForKey:(NSString *)key MTR_UNSTABLE_API;
 
 /**
  *
  * List of all client data keys stored
  *
  */
-- (NSArray * _Nullable)clientDataKeysForEndpointID:(NSNumber *)endpointID MTR_NEWLY_AVAILABLE;
+- (NSArray * _Nullable)clientDataKeysForEndpointID:(NSNumber *)endpointID MTR_UNSTABLE_API;
 
 /**
  *
@@ -303,7 +303,7 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * @param key           NSString * for the key to store the value as
  * @param endpointID    NSNumber * for the endpoint to associate the metadata with
  */
-- (id<NSSecureCoding> _Nullable)clientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID MTR_NEWLY_AVAILABLE;
+- (id<NSSecureCoding> _Nullable)clientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID MTR_UNSTABLE_API;
 
 /**
  *
@@ -313,7 +313,7 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * @param endpointID    NSNumber * for the endpoint to associate the metadata with
  * @param value         id <NSSecureCoding> for the value to store
  */
-- (void)setClientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID value:(id<NSSecureCoding>)value MTR_NEWLY_AVAILABLE;
+- (void)setClientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID value:(id<NSSecureCoding>)value MTR_UNSTABLE_API;
 
 /**
  *
@@ -322,7 +322,7 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
  * @param key           NSString * for the key to store the value as
  * @param endpointID    NSNumber * for the endpoint to associate the metadata with
  */
-- (void)removeClientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID MTR_NEWLY_AVAILABLE;
+- (void)removeClientDataForKey:(NSString *)key endpointID:(NSNumber *)endpointID MTR_UNSTABLE_API;
 
 @end
 

src/darwin/Framework/CHIP/templates/MTRBaseClusters.zapt

@@ -40,7 +40,7 @@ NS_ASSUME_NONNULL_BEGIN
 {{#if (isInConfigList
        (concat (asUpperCamelCase cluster preserveAcronyms=true) "::" (asUpperCamelCase command preserveAcronyms=true))
        "LegacyCommandsWithOnlyOptionalArguments")}}
-{{availability cluster command=command minimalRelease="Future"}}; {{! TODO: Use the right thing here when we know what it's called }}
+{{availability cluster command=command minimalRelease="Early 2024"}};
 {{else}}
 {{availability cluster command=command minimalRelease="First major API revamp"}};
 {{/if}}

src/darwin/Framework/CHIP/templates/MTRClusters.zapt

@@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN
 {{#if (isInConfigList
        (concat (asUpperCamelCase cluster preserveAcronyms=true) "::" (asUpperCamelCase command preserveAcronyms=true))
        "LegacyCommandsWithOnlyOptionalArguments")}}
-{{availability cluster command=command minimalRelease="Future"}}; {{! TODO: Use the right thing here when we know what it's called }}
+{{availability cluster command=command minimalRelease="Early 2024"}};
 {{else}}
 {{availability cluster command=command minimalRelease="First major API revamp"}};
 {{/if}}

src/darwin/Framework/CHIP/templates/availability.yaml

@@ -7803,8 +7803,12 @@
               Feature:
                   DeadFrontBehavior: DeadFront
 
-- release: "Future"
-  versions: "future"
+- release: "Early 2024"
+  versions:
+      iOS: "17.4"
+      macOS: "14.4"
+      watchOS: "10.4"
+      tvOS: "17.4"
   introduced:
       clusters:
           - RVCRunMode
@@ -8524,3 +8528,6 @@
               # as the enum.  The old enum name never had the new value name.
               ContentLaunchStatusEnum:
                   - URLNotAvailable
+
+- release: "Future"
+  versions: "future"