Generate combined Javadoc documentation (#791)

* feat: generate combined Javadoc documentation * feat: add Circle CI step with documentation * feat: config corrections 1 * feat: publishing to docs branch * feat: config corrections 2 * feat: config corrections 3 * feat: config corrections 4 * feat: config corrections 5 * feat: add custom title * feat: add package info for all public packages * feat: add header documentation to the public classes * feat: add documentation to the main public methods * fix: header * feat: upload docs with GitHub actions * fix: uploading #1 * fix: uploading #2 * fix: uploading #3 * fix: uploading #4 * fix: uploading #5 * doc: update description * fix: disable publishing with Circle CI * feat: check docs size before commiting --------- Co-authored-by: Yuriy Velichko <[email protected]>
prebid · Oct 3, 2024 · a115219 · a115219
1 parent 0f88c2c
commit a115219
Show file tree

Hide file tree

Showing 103 changed files with 707 additions and 137 deletions.
diff --git a/.github/workflows/upload-docs.yml b/.github/workflows/upload-docs.yml
@@ -0,0 +1,55 @@
+name: Upload Docs Android
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - 'test-doc-*'
+
+jobs:
+  upload-docs:
+
+    runs-on: macos-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+    - name: Generate docs
+      run: |
+        ./gradlew :PrebidMobile:combinedJavadoc
+        cp -r PrebidMobile/build/combinedJavadoc docs_new
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        ref: docs
+        clean: false
+    - name: Commit documentation changes
+      run: |
+        git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git status
+        TAG_NAME=${{ github.ref }}
+        TAG_NAME=${TAG_NAME#refs/tags/}
+        echo "Current tag: $TAG_NAME"
+        ls -l
+        
+        MIN_SIZE=5120
+        if [ -d docs_new ] && [ "$(du -s docs_new | cut -f1)" -ge "$MIN_SIZE" ]; then
+          rm -rf docs
+          cp -r docs_new docs
+          rm -rf docs_new
+        else
+          echo "docs_new directory either does not exist or is too small."
+          exit 1
+        fi
+        git add docs
+        git commit -m "Generate docs - $TAG_NAME"
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: docs
diff --git a/...Mobile-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationBannerUtils.java b/...Mobile-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationBannerUtils.java
@@ -2,8 +2,11 @@
 
 import android.os.Bundle;
 import android.util.Log;
+
 import androidx.annotation.Nullable;
+
 import com.google.android.gms.ads.AdView;
+
 import org.prebid.mobile.LogUtil;
 import org.prebid.mobile.rendering.bidding.data.bid.BidResponse;
 import org.prebid.mobile.rendering.bidding.display.PrebidMediationDelegate;
@@ -14,6 +17,9 @@
 import java.lang.ref.WeakReference;
 import java.util.HashMap;
 
+/**
+ * Banner mediation delegate.
+ */
 public class AdMobMediationBannerUtils implements PrebidMediationDelegate {
 
     private static final String TAG = "BannerMediationUtils";

diff --git a/...-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationInterstitialUtils.java b/...-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationInterstitialUtils.java
@@ -1,12 +1,17 @@
 package org.prebid.mobile.admob;
 
 import android.os.Bundle;
+
 import androidx.annotation.Nullable;
+
 import org.prebid.mobile.rendering.bidding.data.bid.BidResponse;
 import org.prebid.mobile.rendering.bidding.display.PrebidMediationDelegate;
 
 import java.util.HashMap;
 
+/**
+ * Internal mediation delegate.
+ */
 public class AdMobMediationInterstitialUtils implements PrebidMediationDelegate {
 
     private final Bundle extras;

diff --git a/...bile-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationRewardedUtils.java b/...bile-admobAdapters/src/main/java/org/prebid/mobile/admob/AdMobMediationRewardedUtils.java
@@ -1,12 +1,17 @@
 package org.prebid.mobile.admob;
 
 import android.os.Bundle;
+
 import androidx.annotation.Nullable;
+
 import org.prebid.mobile.rendering.bidding.data.bid.BidResponse;
 import org.prebid.mobile.rendering.bidding.display.PrebidMediationDelegate;
 
 import java.util.HashMap;
 
+/**
+ * Internal mediation delegate.
+ */
 public class AdMobMediationRewardedUtils implements PrebidMediationDelegate {
 
     private final Bundle extras;

diff --git a/...PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidBannerAdapter.java b/...PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidBannerAdapter.java
@@ -16,6 +16,9 @@
 import org.prebid.mobile.rendering.bidding.display.BidResponseCache;
 import org.prebid.mobile.rendering.bidding.listeners.DisplayViewListener;
 
+/**
+ * Prebid banner adapter for AdMob integration.
+ */
 public class PrebidBannerAdapter extends PrebidBaseAdapter {
 
     public static final String EXTRA_RESPONSE_ID = "PrebidBannerAdapterExtraId";

diff --git a/...e/PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidBaseAdapter.java b/...e/PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidBaseAdapter.java
@@ -21,6 +21,9 @@
 import java.util.HashMap;
 import java.util.List;
 
+/**
+ * Base Prebid adapter for all ad types.
+ */
 public abstract class PrebidBaseAdapter extends Adapter {
 
     private final VersionInfo prebidVersion = getPrebidVersion();

diff --git a/...Mobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidInterstitialAdapter.java b/...Mobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidInterstitialAdapter.java
@@ -12,6 +12,9 @@
 import org.prebid.mobile.rendering.bidding.display.InterstitialController;
 import org.prebid.mobile.rendering.bidding.interfaces.InterstitialControllerListener;
 
+/**
+ * Prebid interstitial adapter for AdMob integration.
+ */
 public class PrebidInterstitialAdapter extends PrebidBaseAdapter {
 
     public static final String EXTRA_RESPONSE_ID = "PrebidInterstitialAdapterExtraId";

diff --git a/...rebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidNativeAdMapper.java b/...rebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidNativeAdMapper.java
@@ -32,6 +32,9 @@
 import java.util.ArrayList;
 import java.util.Map;
 
+/**
+ * Prebid native ad mapper for converting to AdMob native ad.
+ */
 public class PrebidNativeAdMapper extends UnifiedNativeAdMapper {
 
     private final PrebidNativeAd prebidAd;

diff --git a/...PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidNativeAdapter.java b/...PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidNativeAdapter.java
@@ -19,6 +19,9 @@
 import java.util.HashMap;
 import java.util.Set;
 
+/**
+ * Prebid native adapter for AdMob integration.
+ */
 public class PrebidNativeAdapter extends PrebidBaseAdapter {
 
     private static final String TAG = "PrebidNative";

diff --git a/...ebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidRewardedAdapter.java b/...ebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/PrebidRewardedAdapter.java
@@ -13,6 +13,9 @@
 import org.prebid.mobile.rendering.bidding.display.InterstitialController;
 import org.prebid.mobile.rendering.bidding.interfaces.InterstitialControllerListener;
 
+/**
+ * Prebid rewarded adapter for AdMob integration.
+ */
 @Keep
 public class PrebidRewardedAdapter extends PrebidBaseAdapter {
 

diff --git a/...Mobile/PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/package-info.java b/...Mobile/PrebidMobile-admobAdapters/src/main/java/org/prebid/mobile/admob/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Adapters for AdMob mediation integration of the Prebid SDK.
+ */
+package org.prebid.mobile.admob;
diff --git a/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/AdUnit.java b/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/AdUnit.java
@@ -51,6 +51,9 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Base ad unit for the original API.
+ */
 public abstract class AdUnit {
 
     protected AdUnitConfiguration configuration = new AdUnitConfiguration();
@@ -84,26 +87,38 @@ public void setAutoRefreshPeriodMillis(
         configuration.setAutoRefreshDelay(periodMillis / 1000);
     }
 
+    /**
+     * Auto refresh interval for banner ad.
+     */
     public void setAutoRefreshInterval(
             @IntRange(from = AUTO_REFRESH_DELAY_MIN / 1000, to = AUTO_REFRESH_DELAY_MAX / 1000) int seconds
     ) {
         configuration.setAutoRefreshDelay(seconds);
     }
 
+    /**
+     * Resumes auto refresh interval after stopping.
+     */
     public void resumeAutoRefresh() {
         LogUtil.verbose("Resuming auto refresh...");
         if (bidLoader != null) {
             bidLoader.setupRefreshTimer();
         }
     }
 
+    /**
+     * Stops auto refresh interval.
+     */
     public void stopAutoRefresh() {
         LogUtil.verbose("Stopping auto refresh...");
         if (bidLoader != null) {
             bidLoader.cancelRefresh();
         }
     }
 
+    /**
+     * Destroy ad unit and stop downloading.
+     */
     public void destroy() {
         if (bidLoader != null) {
             bidLoader.destroy();
@@ -124,7 +139,14 @@ public void fetchDemand(@NonNull final OnCompleteListener2 listener) {
         });
     }
 
-    public void fetchDemand(Object adObj, @NonNull OnCompleteListener listener) {
+    /**
+     * Loads ad and applies keywords to the ad object.
+     *
+     * @param adObject AdMob's ({@code AdManagerAdRequest} or {@code AdManagerAdRequest.Builder})
+     *                 or AppLovin's ({@code MaxNativeAdLoader}) ad object
+     * @param listener callback when operation is completed (success or fail)
+     */
+    public void fetchDemand(Object adObject, @NonNull OnCompleteListener listener) {
         if (TextUtils.isEmpty(PrebidMobile.getPrebidServerAccountId())) {
             LogUtil.error("Empty account id.");
             listener.onComplete(ResultCode.INVALID_ACCOUNT_ID);
@@ -167,8 +189,8 @@ public void fetchDemand(Object adObj, @NonNull OnCompleteListener listener) {
             return;
         }
 
-        if (Util.supportedAdObject(adObj) || allowNullableAdObject) {
-            adObject = adObj;
+        if (Util.supportedAdObject(adObject) || allowNullableAdObject) {
+            this.adObject = adObject;
             bidLoader = new BidLoader(
                     configuration,
                     createBidListener(listener)
@@ -185,12 +207,17 @@ public void fetchDemand(Object adObj, @NonNull OnCompleteListener listener) {
 
             bidLoader.load();
         } else {
-            adObject = null;
+            this.adObject = null;
             listener.onComplete(ResultCode.INVALID_AD_OBJECT);
         }
 
     }
 
+    /**
+     * Loads ad and saves it to cache.
+     *
+     * @param listener callback when operation is completed (success or fail)
+     */
     public void fetchDemand(OnFetchDemandResult listener) {
         if (listener == null) {
             LogUtil.error("Parameter OnFetchDemandResult in fetchDemand() must be not null.");
@@ -307,6 +334,7 @@ public void addContextKeywords(Set<String> keywords) {
 
     /**
      * This method allows to remove specific context keyword from adunit context targeting
+     *
      * @deprecated Use removeExtKeyword
      */
     @Deprecated
@@ -404,9 +432,13 @@ public void setGpid(@Nullable String gpid) {
     }
 
     @Nullable
-    public String getOrtbConfig() { return configuration.getOrtbConfig();}
+    public String getOrtbConfig() {
+        return configuration.getOrtbConfig();
+    }
 
-    public void setOrtbConfig(@Nullable String ortbConfig) {configuration.setOrtbConfig(ortbConfig);}
+    public void setOrtbConfig(@Nullable String ortbConfig) {
+        configuration.setOrtbConfig(ortbConfig);
+    }
 
     protected BidRequesterListener createBidListener(OnCompleteListener originalListener) {
         return new BidRequesterListener() {

diff --git a/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerAdUnit.java b/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerAdUnit.java
@@ -25,26 +25,41 @@
 import java.util.EnumSet;
 import java.util.HashSet;
 
+/**
+ * Original API banner ad unit for displaying banner ad.
+ */
 public class BannerAdUnit extends BannerBaseAdUnit {
 
+    /**
+     * Default constructor for banner ad.
+     *
+     * @param configId config id
+     * @param width    ad width
+     * @param height   ad height
+     */
     public BannerAdUnit(@NonNull String configId, int width, int height) {
         super(configId, EnumSet.of(AdFormat.BANNER));
         configuration.addSize(new AdSize(width, height));
     }
 
     /**
-     * Constructor for multi-format or video banner request.
+     * Constructor with ad formats.
      *
-     * @param adUnitFormats <p>
-     *                      for multi-format request `EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO);`
-     *                      <p>
-     *                      for video banner `EnumSet.of(AdUnitFormat.VIDEO);`
+     * @param configId      config id
+     * @param width         ad width
+     * @param height        ad height
+     * @param adUnitFormats ad formats ({@link AdUnitFormat}). <br>
+     *                      For multi-format request {@code EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO);} <br>
+     *                      For only video request {@code EnumSet.of(AdUnitFormat.VIDEO);}
      */
     public BannerAdUnit(@NonNull String configId, int width, int height, EnumSet<AdUnitFormat> adUnitFormats) {
         super(configId, AdFormat.fromSet(adUnitFormats, false));
         configuration.addSize(new AdSize(width, height));
     }
 
+    /**
+     * Add additional size.
+     */
     public void addAdditionalSize(int width, int height) {
         configuration.addSize(new AdSize(width, height));
     }

diff --git a/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerBaseAdUnit.java b/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerBaseAdUnit.java
@@ -25,7 +25,7 @@
 import java.util.List;
 
 /**
- * Contains Banner and Video parameters.
+ * Base banner ad unit with banner and video parameters.
  */
 public abstract class BannerBaseAdUnit extends AdUnit {
 
@@ -89,6 +89,7 @@ public void setOrtbConfig(@Nullable String ortbConfig) {
     }
 
     /**
+     * Banner parameters.
      * Describes an <a href="https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf">OpenRTB</a> banner object
      */
     @Deprecated

diff --git a/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerParameters.java b/PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/BannerParameters.java
@@ -8,7 +8,9 @@
 import java.util.Set;
 
 /**
- * Describes an <a href="https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf">OpenRTB</a> banner object
+ * Banner parameters for the
+ * <a href="https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf">OpenRTB</a>
+ * banner object.
  */
 public class BannerParameters {