docs: add inline docs for both new and deprecated API (#45)

* fixup formatting
muxinc · Oct 30, 2024 · 758e9be · 758e9be
1 parent e24ae15
commit 758e9be
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 12 deletions.
diff --git a/Sources/MuxStatsGoogleIMAPlugin/MUXSDKIMAAdsListener.m b/Sources/MuxStatsGoogleIMAPlugin/MUXSDKIMAAdsListener.m
@@ -22,15 +22,15 @@ @implementation MUXSDKIMAAdsListener
 
 
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-      monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader {
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader {
     return [self initWithPlayerBinding:binding
                                options:MUXSDKIMAAdsListenerOptionsNone
                    monitoringAdsLoader:adsLoader];
 }
 
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-                    options:(MUXSDKIMAAdsListenerOptions)options
-        monitoringAdsLoader:(IMAAdsLoader *)adsLoader {
+                              options:(MUXSDKIMAAdsListenerOptions)options
+                  monitoringAdsLoader:(IMAAdsLoader *)adsLoader {
     self = [super init];
 
     if (self) {

diff --git a/Sources/MuxStatsGoogleIMAPlugin/MuxImaListener.m b/Sources/MuxStatsGoogleIMAPlugin/MuxImaListener.m
@@ -19,15 +19,15 @@ @implementation MuxImaListener
 
 
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-      monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader {
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader {
     return [self initWithPlayerBinding:binding
                                options:MuxImaListenerOptionsNone
                    monitoringAdsLoader:adsLoader];
 }
 
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-                    options:(MuxImaListenerOptions)options
-               monitoringAdsLoader:(IMAAdsLoader *)adsLoader {
+                              options:(MuxImaListenerOptions)options
+                  monitoringAdsLoader:(IMAAdsLoader *)adsLoader {
     self = [super init];
 
     if (self) {

diff --git a/Sources/MuxStatsGoogleIMAPlugin/include/MUXSDKIMAAdsListener.h b/Sources/MuxStatsGoogleIMAPlugin/include/MUXSDKIMAAdsListener.h
@@ -23,19 +23,102 @@ typedef NS_OPTIONS(NSUInteger, MUXSDKIMAAdsListenerOptions) {
     MUXSDKIMAAdsListenerOptionsPictureInPicture        = 1 << 0,
 };
 
+/// Use `MUXSDKIMAAdsListener` to intercept `IMAAdsManager`
+/// and `IMAAdsLoader` events from the IMA SDK on behalf of
+/// your application.
 @interface MUXSDKIMAAdsListener : NSObject<IMAAdsManagerDelegate, IMAAdsLoaderDelegate>
 
+/// Your applications ads manager delegate, if configured
 @property (nonatomic, weak, nullable) id<IMAAdsManagerDelegate> customerAdsManagerDelegate;
+
+/// Your applications ads loader delegate, if configured
 @property (nonatomic, weak, nullable) id<IMAAdsLoaderDelegate> customerAdsLoaderDelegate;
 
+/// Initializes `MUXSDKIMAAdsListener`, automatically monitors
+/// the IMA ad playback, and notifies the Mux Data SDK at key
+/// points in the ad lifecycle.
+///
+/// After initialization, delegate calls from the provided
+/// IMA ads loader will be intercepted and translated into
+/// `MUXSDKPlaybackEvent`.
+///
+/// These playback events will then be forwarded on to the
+/// supplied player binding and when reported to Mux will
+/// appear on your Dashboard event timeline with other
+/// playback events.
+///
+/// - Parameters:
+///   - binding: player binding that will receive events
+///   concerning ad playback
+///   - adsLoader: ads loader whose delegate calls will be
+///   monitored, make sure to set your own `IMAAdsLoaderDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-        monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+
+/// Initializes `MUXSDKIMAAdsListener`, automatically monitors
+/// the IMA ad playback, and notifies the Mux Data SDK at key
+/// points in the ad lifecycle.
+///
+/// After initialization, delegate calls from the provided
+/// IMA ads loader will be intercepted and translated into
+/// `MUXSDKPlaybackEvent`.
+///
+/// These playback events will then be forwarded on to the
+/// supplied player binding and when reported to Mux will
+/// appear on your Dashboard event timeline with other
+/// playback events.
+///
+/// - Parameters:
+///   - binding: player binding that will receive events
+///   concerning ad playback
+///   - options: options to indicate the starting state
+///   of the player
+///   - adsLoader: ads loader whose delegate calls will be
+///   monitored, make sure to set your own `IMAAdsLoaderDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-                    options:(MUXSDKIMAAdsListenerOptions)options
-        monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+                              options:(MUXSDKIMAAdsListenerOptions)options
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+
+/// Called when an `IMAAdsManager` is available to your
+/// application. Like `IMAAdsLoader`, delegate
+/// calls from the ads manager will be intercepted. Playback
+/// events will be forwarded to the Mux Data player binding
+/// configured during initialization
+///
+/// - Parameter adsManager: ads manager who delegate calls
+/// will be monitored, make sure to set your own `IMAAdsManagerDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (void)monitorAdsManager:(IMAAdsManager *)adsManager;
+
+/// Signals if the monitored player is being displayed as
+/// picture in picture during ad playback.
+/// - Parameter isPictureInPicture: Pass ``YES`` to indicate
+/// the player is current displayed using picture in picture.
+/// Pass ``NO`` otherwise.
 - (void)setPictureInPicture:(BOOL)isPictureInPicture;
+
+/// Signals a client ad request made by your application.
+///
+/// Call as soon as possible after sending the request to
+/// ensure accuracy.
+///
+/// - Parameter request: a client ad request your application
+/// just made
 - (void)clientAdRequest:(IMAAdsRequest *)request;
+
+/// Signals a stream ad request has been made by your
+/// application.
+///
+/// Call as soon as possible after sending the request to
+/// ensure accuracy.
+///
+/// - Parameter request: a client ad request your application
+/// just made
 - (void)daiAdRequest:(IMAStreamRequest *)request;
 
 @end

diff --git a/Sources/MuxStatsGoogleIMAPlugin/include/MuxImaListener.h b/Sources/MuxStatsGoogleIMAPlugin/include/MuxImaListener.h
@@ -24,20 +24,111 @@ typedef NS_OPTIONS(NSUInteger, MuxImaListenerOptions) {
     MuxImaListenerOptionsPictureInPicture        = 1 << 0,
 };
 
+/// Use `MuxImaListener` to intercept `IMAAdsManager`
+/// and `IMAAdsLoader` events from the IMA SDK on behalf of
+/// your application.
+///
+/// **Note: this class is deprecated and will be removed in
+/// a future SDK release. Please switch to using `MUXSDKIMAAdsListener`.**
 NS_CLASS_DEPRECATED_IOS(2_0, 12_0, "Use MUXSDKIMAAdsListener instead.")
 @interface MuxImaListener : NSObject<IMAAdsManagerDelegate, IMAAdsLoaderDelegate>
 
+/// Your applications ads manager delegate, if configured
 @property (nonatomic, weak, nullable) id<IMAAdsManagerDelegate> customerAdsManagerDelegate;
+
+/// Your applications ads loader delegate, if configured
 @property (nonatomic, weak, nullable) id<IMAAdsLoaderDelegate> customerAdsLoaderDelegate;
 
+/// Initializes `MuxImaListener`, automatically monitors
+/// the IMA ad playback, and notifies the Mux Data SDK at key
+/// points in the ad lifecycle.
+///
+/// After initialization, delegate calls from the provided
+/// IMA ads loader will be intercepted and translated into
+/// `MUXSDKPlaybackEvent`.
+///
+/// These playback events will then be forwarded on to the
+/// supplied player binding and when reported to Mux will
+/// appear on your Dashboard event timeline with other
+/// playback events.
+///
+/// - Parameters:
+///   - binding: player binding that will receive events
+///   concerning ad playback
+///   - adsLoader: ads loader whose delegate calls will be
+///   monitored, make sure to set your own `IMAAdsLoaderDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-        monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+
+
+/// Initializes `MuxImaListener`, automatically monitors
+/// the IMA ad playback, and notifies the Mux Data SDK at key
+/// points in the ad lifecycle.
+///
+/// After initialization delegate calls from the provided
+/// IMA ads loader will be intercepted and translated into
+/// `MUXSDKPlaybackEvent`.
+///
+/// These playback events will then be forwarded on to the
+/// supplied player binding and when reported to Mux will
+/// appear on your Dashboard event timeline with other
+/// playback events.
+///
+/// - Parameters:
+///   - binding: player binding that will receive events
+///   concerning ad playback
+///   - options: options to indicate the starting state
+///   of the player
+///   - adsLoader: ads loader whose delegate calls will be
+///   monitored, make sure to set your own `IMAAdsLoaderDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (instancetype)initWithPlayerBinding:(MUXSDKPlayerBinding *)binding
-                    options:(MuxImaListenerOptions)options
-        monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+                              options:(MuxImaListenerOptions)options
+                  monitoringAdsLoader:(nullable IMAAdsLoader *)adsLoader;
+
+
+/// Called when an `IMAAdsManager` is available to your
+/// application. Like `IMAAdsLoader`, delegate
+/// calls from the ads manager will be intercepted. Playback
+/// events will be forwarded to the Mux Data player binding
+/// configured during initialization
+///
+/// - Parameter adsManager: ads manager who delegate calls
+/// will be monitored, make sure to set your own `IMAAdsManagerDelegate`
+///   **before** calling this initializer. Delegate calls
+///   will then be automatically forwarded to your delegate.
 - (void)monitorAdsManager:(IMAAdsManager *)adsManager;
+
+
+/// Signals if the monitored player is being displayed as
+/// picture in picture during ad playback.
+/// - Parameter isPictureInPicture: Pass ``YES`` to indicate
+/// the player is current displayed using picture in picture.
+/// Pass ``NO`` otherwise.
 - (void)setPictureInPicture:(BOOL)isPictureInPicture;
+
+
+/// Signals a client ad request made by your application.
+///
+/// Call as soon as possible after sending the request to
+/// ensure accuracy.
+///
+/// - Parameter request: a client ad request your application
+/// just made
 - (void)clientAdRequest:(IMAAdsRequest *)request;
+
+
+/// Signals a stream ad request has been made by your
+/// application.
+///
+/// Call as soon as possible after sending the request to
+/// ensure accuracy.
+///
+/// - Parameter request: a client ad request your application
+/// just made
 - (void)daiAdRequest:(IMAStreamRequest *)request;
 
 @end