Added documentation to code

Author: rt4914

app/src/main/java/com/foremlibrary/app/MainActivity.kt

@@ -12,6 +12,7 @@ private const val WEB_VIEW_FRAGMENT_RESULT_LISTENER_KEY =
 private const val DEV_TO = "https://dev.to"
 private const val MMA_LIFE = "https://www.thismmalife.com/"
 
+/** Helper activity which connects with foremwebview module.*/
 class MainActivity : AppCompatActivity() {
 
     private lateinit var backImageView: ImageView

build.gradle

@@ -2,7 +2,6 @@ buildscript {
     repositories {
         google()
         mavenCentral()
-        // maven { url 'https://jitpack.io' }
     }
     dependencies {
         classpath "com.android.tools.build:gradle:4.1.3"

foremwebview/build.gradle

@@ -11,10 +11,10 @@ android {
         minSdk 21
         targetSdk 31
         versionCode 1
-        versionName "1.0.5"
+        versionName "1.0.6"
 
         buildConfigField("String", "ANDROID_BRIDGE", "\"AndroidBridge\"")
-        buildConfigField("String", "FOREM_AGENT_EXTENSION", "\"ForemWebView/1.0.5\"")
+        buildConfigField("String", "FOREM_AGENT_EXTENSION", "\"ForemWebView/1.0.6\"")
         buildConfigField("String", "PASSPORT_AGENT_EXTENSION", "\"ForemWebView/passport\"")
 
         consumerProguardFiles "consumer-rules.pro"
@@ -67,7 +67,7 @@ afterEvaluate {
 
                 groupId = 'com.github.forem'
                 artifactId = 'ForemWebView-android'
-                version = '1.0.5'
+                version = '1.0.6'
             }
         }
     }

foremwebview/src/main/java/com/forem/webview/AndroidWebViewBridge.kt

@@ -17,6 +17,7 @@ import com.google.gson.Gson
 import org.json.JSONObject
 import java.util.*
 
+/** Bridge between WebView and its client where all the javascript interfaces are designed. */
 class AndroidWebViewBridge(
     private val context: Activity,
     private val webViewClient: ForemWebViewClient
@@ -37,18 +38,35 @@ class AndroidWebViewBridge(
         }
     }
 
+    /**
+     * Function which gets called once the webview has fully loaded a valid forem instance which
+     * contains the details of forem like name, logo, etc.
+     *
+     * @param foremMetaDataJsonObject an object which contains meta data of forem.
+     */
     @JavascriptInterface
     fun processForemMetaData(foremMetaDataJsonObject: String) {
         var foremMetaDataMap: Map<String, String> = HashMap()
         foremMetaDataMap = Gson().fromJson(foremMetaDataJsonObject, foremMetaDataMap.javaClass)
         webViewClient.foremMetaDataReceived(foremMetaDataMap)
     }
 
+    /**
+     * Function which gets called by website when an error occurs.
+     *
+     * @param errorTag tag required for log message.
+     * @param errorMessage message required for log message.
+     */
     @JavascriptInterface
     fun logError(errorTag: String, errorMessage: String) {
         Log.e(errorTag, errorMessage)
     }
 
+    /**
+     * Function which gets called once the user has successfully logged-in.
+     *
+     * @param message contains user related meta data like name, id, etc.
+     */
     @JavascriptInterface
     fun userLoginMessage(message: String) {
         val userDataObject = JSONObject(message)
@@ -59,17 +77,28 @@ class AndroidWebViewBridge(
         }
     }
 
+    /**
+     * Function which gets called once the user has successfully logged-out.
+     *
+     * @param message contains user related data.
+     */
     @JavascriptInterface
     fun userLogoutMessage(message: String) {
         // User logged-out
         webViewClient.userLoggedOut()
     }
 
+    /**
+     * Function which gets triggered when user does any action related to podcast.
+     *
+     * @param message contains information related to podcast like its url, play action, pause
+     *    action, title, etc. which can be used to load th podcast in audio service.
+     */
     @JavascriptInterface
     fun podcastMessage(message: String) {
         // Reference: https://stackoverflow.com/questions/9446868/access-ui-from-javascript-on-android
         context.runOnUiThread {
-            var map: Map<String, String> = java.util.HashMap()
+            var map: Map<String, String> = HashMap()
             map = Gson().fromJson(message, map.javaClass)
             when (map["action"]) {
                 "load" -> loadPodcast(map["url"])
@@ -115,7 +144,7 @@ class AndroidWebViewBridge(
         }
     }
 
-    fun podcastTimeUpdate() {
+    private fun podcastTimeUpdate() {
         audioService?.let {
             val time = it.currentTimeInSec() / 1000
             val duration = it.durationInSec() / 1000
@@ -133,6 +162,11 @@ class AndroidWebViewBridge(
         }
     }
 
+    /**
+     * Function which gets triggered when user first clicks on video in webview player.
+     *
+     * @param message contains information like video url and current-time in video.
+     */
     @JavascriptInterface
     fun videoMessage(message: String) {
         var map: Map<String, String> = HashMap()
@@ -157,6 +191,8 @@ class AndroidWebViewBridge(
     /**
      * This method is used to open the native share-sheet of Android when simple text is to be
      * shared from the web-view.
+     *
+     * @param text contains the text which needs to be shared natively.
      */
     @JavascriptInterface
     fun shareText(text: String) {
@@ -171,23 +207,41 @@ class AndroidWebViewBridge(
         context.startActivity(shareIntent)
     }
 
+    /**
+     * This function copies the text natively to clipboard.
+     *
+     * @param copyText contains the text which gets saved to clipboard natively.
+     */
     @JavascriptInterface
     fun copyToClipboard(copyText: String) {
         val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as? ClipboardManager
         val clipData = ClipData.newPlainText("Forem", copyText)
         clipboard?.setPrimaryClip(clipData)
     }
 
+    /**
+     * Shows toast in android app triggered via website.
+     *
+     * @param message required to be displayed in Toast.
+     */
     @JavascriptInterface
     fun showToast(message: String) {
         Toast.makeText(context, message, Toast.LENGTH_LONG).show()
     }
 
+    /**
+     * Helps in sending the timer value for the video to the backend.
+     *
+     * @param seconds new updated value of current time in video.
+     */
     fun updateTimer(seconds: String) {
         val message = mapOf("action" to "tick", "currentTime" to seconds)
         webViewClient.sendBridgeMessage(BridgeMessageType.VIDEO, message)
     }
 
+    /**
+     * Helps in sending the information to webview that the video has been paused.
+     */
     fun videoPlayerPaused() {
         webViewClient.sendBridgeMessage(BridgeMessageType.VIDEO, mapOf("action" to "pause"))
     }

foremwebview/src/main/java/com/forem/webview/BridgeMessageType.kt

@@ -1,6 +1,9 @@
 package com.forem.webview
 
+/** Enum to determine common actions within podcast and video. */
 enum class BridgeMessageType(val messageType: String) {
+    /** PODCAST enum. */
     PODCAST("podcast"),
+    /** VIDEO enum. */
     VIDEO("video")
 }

foremwebview/src/main/java/com/forem/webview/FileChooserListener.kt

@@ -3,6 +3,11 @@ package com.forem.webview
 import android.net.Uri
 import android.webkit.ValueCallback
 
+/** Interface to open file chooser natively in android. */
 interface FileChooserListener {
+    /**
+     * Function which passes the filePathCallback which gets used again once the images are selected
+     * natively.
+     */
     fun openFileChooser(filePathCallback: ValueCallback<Array<Uri>>?)
 }

foremwebview/src/main/java/com/forem/webview/ForemWebChromeClient.kt

@@ -5,6 +5,7 @@ import android.webkit.ValueCallback
 import android.webkit.WebChromeClient
 import android.webkit.WebView
 
+/** Class which extends WebChromeClient to override all out-of WebView actions. */
 class ForemWebChromeClient(
     private val fileChooserListener: FileChooserListener
 ) : WebChromeClient() {

foremwebview/src/main/java/com/forem/webview/ForemWebViewClient.kt

@@ -17,6 +17,10 @@ import org.json.JSONObject
 import java.net.URL
 import java.util.Locale
 
+/**
+ * Class which extends WebViewClient to override all functions and implement custom functionalities
+ * within the WebView.
+ */
 @SuppressLint("DefaultLocale")
 class ForemWebViewClient(
     private val activity: Activity?,
@@ -37,6 +41,11 @@ class ForemWebViewClient(
         setBaseUrl(originalUrl)
     }
 
+    /**
+     * Sets the base url.
+     *
+     * @param baseUrl is the url which is basically the host.
+     */
     fun setBaseUrl(baseUrl: String) {
         this.baseUrl = baseUrl
     }
@@ -47,6 +56,12 @@ class ForemWebViewClient(
 
     private var token: String? = null
 
+    /**
+     * Function called via [AndroidWebViewBridge] when it successfully fetches the meta data of
+     * forem instance.
+     *
+     * @param foremMetaDataMap is a map of forem related meta data.
+     */
     fun foremMetaDataReceived(foremMetaDataMap: Map<String, String>) {
         if (UrlChecks.checkUrlIsCorrect(baseUrl)) {
             val host = URL(baseUrl).host
@@ -59,15 +74,27 @@ class ForemWebViewClient(
         }
     }
 
+    /**
+     * Function which gets called when user is logged-in successfully.
+     *
+     * @param userId unique user if associated with current user.
+     */
     fun userLoggedIn(userId: Int) {
         this.userId = userId
         generateFirebaseToken()
     }
 
+    /**
+     * Gets called when user logs-out of the website.
+     */
     fun userLoggedOut() {
         unregisterDevice()
     }
 
+    /**
+     * Function to set the clearHistory boolean to true.
+     * @param
+     */
     fun clearHistory() {
         clearHistory = true
     }
@@ -232,6 +259,13 @@ class ForemWebViewClient(
         }
     }
 
+    /**
+     * This function gets called from [AndroidWebViewBridge] whenever some information needs to be
+     * sent to the website from the android device.
+     *
+     * @param type can be either podcast of video.
+     * @param message contains the information along with actions which needs to be sent.
+     */
     fun sendBridgeMessage(type: BridgeMessageType, message: Map<String, Any>) {
         val payload = mutableMapOf<String, Any>()
         payload.putAll(message)

foremwebview/src/main/java/com/forem/webview/ForemWebViewSession.kt

@@ -2,12 +2,22 @@ package com.forem.webview
 
 import android.util.Log
 
+/**
+ * Helper class to play and pause video in [VideoPlayerActivity] and send that information to
+ * website.
+ */
 class ForemWebViewSession {
 
+    /** The [AndroidWebViewBridge] instance required to call javascript interface functions. */
     var androidWebViewBridge: AndroidWebViewBridge? = null
 
     private var instance: ForemWebViewSession? = null
 
+    /**
+     * Function which creates a new instance of this class or shares the old instance.
+     *
+     * @return instance of [ForemWebViewSession].
+     */
     fun getInstance(): ForemWebViewSession? {
         if (instance == null) {
             synchronized(ForemWebViewSession::class.java) {
@@ -19,13 +29,19 @@ class ForemWebViewSession {
         return instance
     }
 
+    /** Gets called whenever the video gets paused or the [VideoPlayerActivity] is destroyed. */
     fun videoPlayerPaused() {
         if (androidWebViewBridge == null) {
             Log.e("ForemWebViewSession", "videoPlayerPaused: androidWebViewBridge is null")
         }
         androidWebViewBridge?.videoPlayerPaused()
     }
 
+    /**
+     * This function regularly updates the timer for the video on backend.
+     *
+     * @return seconds at which the video is at currently.
+     */
     fun videoPlayerTimerUpdate(seconds: String) {
         if (androidWebViewBridge == null) {
             Log.e("ForemWebViewSession", "videoPlayerTimerUpdate: androidWebViewBridge is null")

foremwebview/src/main/java/com/forem/webview/UrlChecks.kt

@@ -8,6 +8,7 @@ import java.net.URISyntaxException
 import java.net.URL
 import java.util.Locale
 
+/** Helper object which checks different urls with helper functions. */
 object UrlChecks {
     private val overrideUrlList = listOf(
         "account.forem.com",
@@ -23,6 +24,13 @@ object UrlChecks {
         "https://accounts.google.co.in"
     )
 
+    /**
+     * Function which determines the url type w.r.t. to host url.
+     *
+     * @param url which will get compared with the host.
+     * @param host is the main url for comparison.
+     * @return an emum described within from [UrlType]
+     */
     @SuppressLint("DefaultLocale")
     fun getURLType(url: String, host: String): UrlType {
         // TODO(#178): Special case- if URL is is https://m.facebook.com/ and host is www.facebook.com
@@ -51,6 +59,12 @@ object UrlChecks {
         }
     }
 
+    /**
+     * Checks if text is correct valid url or not.
+     * @param url which needs to be checked.
+     * @throws MalformedURLException or URISyntaxException or Exception if url is not valid.
+     * @return true if its a valid url.
+     */
     fun checkUrlIsCorrect(url: String): Boolean {
         return try {
             val checkURL = URL(url)
@@ -65,6 +79,14 @@ object UrlChecks {
         }
     }
 
+    /**
+     * Checks if the url is valid and then append/adjust to https:// prefix
+     *
+     * @param url which needs to be corrected.
+     * @return a valid https url
+     *
+     * @sample: if url is "http://example.com" it will return "https://example.com"
+     */
     fun checkAndAppendHttpsToUrl(url: String): String {
         return if (url.isValidUrl()) {
             when {