From 27798e9298b2eec06e44213ee68e6a8abe2aef3d Mon Sep 17 00:00:00 2001
From: Aldo Becerril <aldobecerril@google.com>
Date: Thu, 15 Feb 2024 11:12:46 -0800
Subject: [PATCH] Better documentation for classes

---
 .../FlutterMediationExtras.java               | 22 +++++++++++++++++++
 .../ios/Classes/FLTMediationExtras.h          | 11 ++++++++++
 .../lib/src/ad_containers.dart                |  6 ++---
 .../lib/src/mediation_extras.dart             |  2 +-
 4 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/packages/google_mobile_ads/android/src/main/java/io/flutter/plugins/googlemobileads/FlutterMediationExtras.java b/packages/google_mobile_ads/android/src/main/java/io/flutter/plugins/googlemobileads/FlutterMediationExtras.java
index 82fd13773..b1d1fe90d 100644
--- a/packages/google_mobile_ads/android/src/main/java/io/flutter/plugins/googlemobileads/FlutterMediationExtras.java
+++ b/packages/google_mobile_ads/android/src/main/java/io/flutter/plugins/googlemobileads/FlutterMediationExtras.java
@@ -19,8 +19,30 @@
 import com.google.android.gms.ads.mediation.MediationExtrasReceiver;
 import java.util.Map;
 
+/**
+ * Mediation Adapters that require extra parameters provide implementations of this interface to
+ * further be sent to the {@link com.google.android.gms.ads.AdRequest}
+ *
+ * Implementation will receive the Map of Extras via the
+ * {@link FlutterMediationExtras#setMediationExtras} which the implementation must store and later
+ * parse to the proper pair of Class and Bundle values returned by
+ * {@link FlutterMediationExtras#getMediationExtras()}
+ */
 public interface FlutterMediationExtras {
+
+  /**
+   * Called when the {@link FlutterAdRequest} is parsed into an
+   * {@link com.google.android.gms.ads.AdRequest}.
+   *
+   * @return The parsed values to be sent to the
+   *     {@link com.google.android.gms.ads.AdRequest.Builder#addNetworkExtrasBundle}
+   */
   Pair<Class<? extends MediationExtrasReceiver>, Bundle> getMediationExtras();
 
+  /**
+   * Pair of key-values to be stored and later be parsed into a {@link Bundle}.
+   *
+   * @param extras Received from the dart layer through the MediationExtras class.
+   */
   void setMediationExtras(Map<String, Object> extras);
 }
diff --git a/packages/google_mobile_ads/ios/Classes/FLTMediationExtras.h b/packages/google_mobile_ads/ios/Classes/FLTMediationExtras.h
index a6534055c..966f6c654 100644
--- a/packages/google_mobile_ads/ios/Classes/FLTMediationExtras.h
+++ b/packages/google_mobile_ads/ios/Classes/FLTMediationExtras.h
@@ -15,10 +15,21 @@
 #import <Foundation/Foundation.h>
 #import <GoogleMobileAds/GADAdNetworkExtras.h>
 
+/**
+ * Mediation adapters will provide a class that conforms to this protocol to be
+ * added to the `FLTAdRequest`.
+ */
 @protocol FlutterMediationExtras
 
+// Pair of key-values to be stored received from the dart layer.
 @property NSMutableDictionary *_Nullable extras;
 
+/**
+ * Parses the values in @c extras to the required protocol to append Mediation
+ * extras to the `FLTAdRequest`.
+ *
+ * @return the parsed extra values to an object that conforms to protocol.
+ */
 - (id<GADAdNetworkExtras> _Nonnull)getMediationExtras;
 
 @end
diff --git a/packages/google_mobile_ads/lib/src/ad_containers.dart b/packages/google_mobile_ads/lib/src/ad_containers.dart
index e2dbea932..309395df1 100644
--- a/packages/google_mobile_ads/lib/src/ad_containers.dart
+++ b/packages/google_mobile_ads/lib/src/ad_containers.dart
@@ -198,7 +198,7 @@ class AdRequest {
       this.neighboringContentUrls,
       this.nonPersonalizedAds,
       this.httpTimeoutMillis,
-      this.mediationExtrasIdentifier,
+      @deprecated this.mediationExtrasIdentifier,
       this.extras,
       this.mediationExtras});
 
@@ -235,8 +235,7 @@ class AdRequest {
   /// Extras to pass to the AdMob adapter.
   final Map<String, String>? extras;
 
-  /// Extras to pass to the Mediations Adapter linked to the instance of the
-  /// [MediationExtras].
+  /// Extra parameters to pass to specific ad adapters.
   final List<MediationExtras>? mediationExtras;
 
   @override
@@ -274,6 +273,7 @@ class AdManagerAdRequest extends AdRequest {
           neighboringContentUrls: neighboringContentUrls,
           nonPersonalizedAds: nonPersonalizedAds,
           httpTimeoutMillis: httpTimeoutMillis,
+          //ignore: deprecated_member_use_from_same_package
           mediationExtrasIdentifier: mediationExtrasIdentifier,
           extras: extras,
           mediationExtras: mediationExtras,
diff --git a/packages/google_mobile_ads/lib/src/mediation_extras.dart b/packages/google_mobile_ads/lib/src/mediation_extras.dart
index dec85f572..c2ecc05f4 100644
--- a/packages/google_mobile_ads/lib/src/mediation_extras.dart
+++ b/packages/google_mobile_ads/lib/src/mediation_extras.dart
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.