Documentation with Dokka and KDoc (#537)

* add documentation for all modules

* add module level documentation

* update readme with testing and documentation

* add documentation to deploy script

* fix comment

* fix js tests

* fix js build

* final customizations for documentation

* add docs for storage

* performance documentation

* add functions, installations and messaging documentation

* add documentation for remote config, crashlytics and database

* add documentation for firebase app

* Added publish docs

* Merge branch 'master' of https://github.com/GitLiveApp/firebase-kotlin-sdk into feat/Documentation

* fix gradle build

---------

Co-authored-by: Andrew Reed <[email protected]>

.github/workflows/publish.yml

@@ -53,4 +53,24 @@ jobs:
       - name: Publish Firebase Performance
         run: ./gradlew :firebase-perf:publish
       - name: Publish Firebase Crashlytics
-        run: ./gradlew :firebase-crashlytics:publish
+        run: ./gradlew :firebase-crashlytics:publish
+  documentation:
+    runs-on: macos-13
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up JDK
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+      - uses: gradle/gradle-build-action@v2
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+      - name: Generate documentation
+        run: ./gradlew dokkaHtmlMultiModule
+      - name: Deploy API documentation to Github Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: ./build/htmlMultiModule/dokka/html
+          target-folder: api

README.md

@@ -288,6 +288,22 @@ You can build and test the project locally.
 3. Install the GitLive plugin into IntelliJ
 4. After a gradle sync then run `publishToMavenLocal`
 
+### Testing
+To run the tests you can use the following gradle tasks:
+
+`./gradlew connectedAndroidTest` (an emulator needs to be running)
+
+`./gradlew iosSimulatorArm64Test`
+
+`./gradlew jsNodeTest`
+
+For some tests you need to have the firebase emulator suite running. After installing them you can run the following command inside the `test` directory:
+
+`firebase emulators:start`
+
+### Documentation
+For every publicly available class or function there needs to be documentation written in the [KDoc syntax](https://kotlinlang.org/docs/kotlin-doc.html).
+
 ### Compatibility with the official [Firebase Android SDK](https://github.com/firebase/firebase-android-sdk)
 
 When this project began, the official Firebase Android SDK was a pure java library and the separate Kotlin extensions (KTX) module consisted of only a few extensions providing some syntactic sugar, for example `Firebase.firestore` instead of `Firebase.getInstance(),` which we naturally copied for the Firebase Kotlin SDK.

build.gradle.kts

@@ -1,6 +1,12 @@
 import org.apache.tools.ant.taskdefs.condition.Os
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import org.gradle.api.tasks.testing.logging.TestLogEvent
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import org.jetbrains.dokka.gradle.AbstractDokkaTask
+import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import java.net.URL
 import java.io.InputStream
 
 plugins {
@@ -10,10 +16,17 @@ plugins {
     alias(libs.plugins.native.cocoapods) apply false
     alias(libs.plugins.test.logger.plugin) apply false
     alias(libs.plugins.ben.manes.versions) apply false
+    alias(libs.plugins.dokka)
     id("base")
     id("testOptionsConvention")
 }
 
+buildscript {
+    dependencies {
+        classpath(libs.dokka.base)
+    }
+}
+
 val compileSdkVersion by extra(34)
 val minSdkVersion by extra(23)
 
@@ -36,10 +49,60 @@ tasks {
     }
 }
 
+private val dokkaCopyrightMessage = "© 2024 GitLive Ltd."
+private val dokkaHomepageUrl = "https://github.com/GitLiveApp/firebase-kotlin-sdk"
+
+tasks.withType<AbstractDokkaTask>().configureEach {
+    val version = project.property("firebase-app.version") as String
+    moduleVersion.set(version)
+    moduleName.set("Firebase Kotlin SDK")
+
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customAssets = listOf(file("documentation/gitlive-logo.png"), file("documentation/homepage.svg"))
+        customStyleSheets = listOf(file("documentation/logo-styles.css"))
+        footerMessage = dokkaCopyrightMessage
+        homepageLink = dokkaHomepageUrl
+    }
+}
+
 subprojects {
 
     group = "dev.gitlive"
-
+
+    val nonDocumentationList = listOf("test-utils", "firebase-common", "firebase-common-internal")
+    val skipDocumentation = nonDocumentationList.contains(project.name)
+    if (!skipDocumentation) {
+        apply(plugin = "org.jetbrains.dokka")
+    }
+
+    this.tasks.withType<DokkaTaskPartial>().configureEach {
+        pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+            footerMessage = dokkaCopyrightMessage
+            separateInheritedMembers = false
+            homepageLink = dokkaHomepageUrl
+        }
+        dokkaSourceSets {
+            configureEach {
+                documentedVisibilities.set(setOf(DokkaConfiguration.Visibility.PUBLIC))
+                includes.setFrom("documentation.md")
+
+                sourceLink {
+                    localDirectory.set(projectDir.resolve("src"))
+                    remoteUrl.set(URL("$dokkaHomepageUrl/tree/master/${project.name}/src"))
+                }
+            }
+            if (this.names.contains("jsMain")) {
+                named("jsMain") {
+                    perPackageOption {
+                        // External files for JS should not be documented since they will not be available
+                        matchingRegex.set(".*.externals.*")
+                        suppress.set(true)
+                    }
+                }
+            }
+        }
+    }
+
     apply(plugin = "com.adarshr.test-logger")
 
     repositories {

documentation/logo-styles.css

@@ -0,0 +1,5 @@
+:root {
+    --dokka-logo-image-url: url('../images/gitlive-logo.png');
+    --dokka-logo-height: 50px;
+    --dokka-logo-width: 50px;
+}

firebase-analytics/documentation.md

@@ -0,0 +1,2 @@
+# Module firebase-analytics
+This module is a direct forward of the Firebase Analytics library. It provides the main functionality, like logging events.

firebase-analytics/src/iosMain/kotlin/dev/gitlive/firebase/analytics/analytics.kt

@@ -64,7 +64,7 @@ actual class FirebaseAnalytics(val ios: FIRAnalytics.Companion) {
 
 actual class FirebaseAnalyticsException(message: String): FirebaseException(message)
 
-suspend inline fun <T> T.await(function: T.(callback: (NSError?) -> Unit) -> Unit) {
+internal suspend inline fun <T> T.await(function: T.(callback: (NSError?) -> Unit) -> Unit) {
     val job = CompletableDeferred<Unit>()
     function { error ->
         if(error == null) {
@@ -76,7 +76,7 @@ suspend inline fun <T> T.await(function: T.(callback: (NSError?) -> Unit) -> Uni
     job.await()
 }
 
-suspend inline fun <T, reified R> T.awaitResult(function: T.(callback: (R?, NSError?) -> Unit) -> Unit): R {
+internal suspend inline fun <T, reified R> T.awaitResult(function: T.(callback: (R?, NSError?) -> Unit) -> Unit): R {
     val job = CompletableDeferred<R?>()
     function { result, error ->
         if(error == null) {

firebase-app/documentation.md

@@ -0,0 +1,2 @@
+# Module firebase-app
+This module is a direct forward of the Firebase App library. It provides the default FirebaseApp instances.

firebase-app/src/commonMain/kotlin/dev/gitlive/firebase/firebase.kt

@@ -12,13 +12,38 @@ import kotlin.jvm.JvmName
 /**
  * Single access point to all firebase sdks from Kotlin.
  *
- * <p>Acts as a target for extension methods provided by sdks.
+ * Acts as a target for extension methods provided by sdks.
  */
 object Firebase
 
+/**
+ * The entry point of Firebase SDKs. It holds common configuration and state for Firebase APIs. Most
+ * applications don't need to directly interact with FirebaseApp.
+ *
+ * For a vast majority of apps, FirebaseInitProvider will handle the initialization of
+ * Firebase for the default project that it's configured to work with, via the data contained in the
+ * app's `google-services.json` file. This `ContentProvider`
+ * is merged into the app's manifest by default when building with Gradle,
+ * and it runs automatically at app launch. No additional lines of code are needed in this
+ * case.
+ *
+ * Any `FirebaseApp` initialization must occur only in the main process of the app.
+ * Use of Firebase in processes other than the main process is not supported and will likely cause
+ * problems related to resource contention.
+ */
 expect class FirebaseApp {
+    /** Returns the unique name of this app. */
     val name: String
+
+    /** Returns the specified [FirebaseOptions]. */
     val options: FirebaseOptions
+
+    /**
+     * Deletes the [FirebaseApp] and all its data. All calls to this [FirebaseApp]
+     * instance will throw once it has been called.
+     *
+     * A no-op if delete was called before.
+     */
     suspend fun delete()
 }
 
@@ -44,22 +69,58 @@ expect fun Firebase.initialize(context: Any? = null, options: FirebaseOptions, n
 val Firebase.options: FirebaseOptions
     get() = Firebase.app.options
 
+/** Configurable Firebase options. */
 data class FirebaseOptions(
+    /** The Google App ID that is used to uniquely identify an instance of an app. */
     val applicationId: String,
+
+    /**
+     * API key used for authenticating requests from your app, e.g.
+     * AIzaSyDdVgKwhZl0sTTTLZ7iTmt1r3N2cJLnaDk, used to identify your app to Google servers.
+     */
     val apiKey: String,
+
+    /** The database root URL, e.g. http://abc-xyz-123.firebaseio.com. */
     val databaseUrl: String? = null,
+
+    /**
+     * The tracking ID for Google Analytics, e.g. UA-12345678-1, used to configure Google Analytics.
+     */
     val gaTrackingId: String? = null,
+
+    /** The Google Cloud Storage bucket name, e.g. abc-xyz-123.storage.firebase.com. */
     val storageBucket: String? = null,
+
+    /** The Google Cloud project ID, e.g. my-project-1234 */
     val projectId: String? = null,
+
+    /**
+     * The Project Number from the Google Developer's console, for example 012345678901, used to
+     * configure Google Cloud Messaging.
+     */
     val gcmSenderId: String? = null,
+
+    /** The auth domain. */
     val authDomain: String? = null
 )
 
+/**
+ * Exception that gets thrown when an operation on Firebase fails.
+ */
 expect open class FirebaseException : Exception
 
+/**
+ * Exception that gets thrown when an operation on Firebase fails.
+ */
 expect class FirebaseNetworkException : FirebaseException
 
+/**
+ * Exception that gets thrown when an operation on Firebase fails.
+ */
 expect open class FirebaseTooManyRequestsException : FirebaseException
 
+/**
+ * Exception that gets thrown when an operation on Firebase fails.
+ */
 expect open class FirebaseApiNotAvailableException : FirebaseException
 

firebase-auth/documentation.md

@@ -0,0 +1,2 @@
+# Module firebase-auth
+This module is a direct forward of the Firebase Authentication library. It provides the main functionality, like authenticating with Google or Apple.

firebase-config/documentation.md

@@ -0,0 +1,2 @@
+# Module firebase-config
+This module is a direct forward of the Firebase Remote Config library. It provides the main functionality, like remote feature flags.