Merge pull request #24 from 05nelsonm/mn/documentation/sample-code

Add sample code/Dokka docs

Author: 05nelsonm

build.gradle

@@ -7,6 +7,7 @@ buildscript {
     }
     dependencies {
         classpath deps.androidGradlePlugin
+        classpath deps.dokka
         classpath deps.kotlin.gradlePlugin
     }
 }

gradle/dependencies.gradle

@@ -29,6 +29,7 @@ ext.deps = [
             liveDataCore: "androidx.arch.core:core-testing:2.1.0",
         ],
     ],
+    dokka: "org.jetbrains.dokka:dokka-gradle-plugin:0.10.1",
     gradleVersions: "com.github.ben-manes:gradle-versions-plugin:0.20.0",
     jtorctl: "info.guardianproject:jtorctl:0.4",
     junit: "junit:junit:4.12",

sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt

@@ -19,6 +19,9 @@ package io.matthewnelson.sampleapp
 import android.app.Application
 import io.matthewnelson.topl_service.TorServiceController
 
+/**
+ * @suppress
+ * */
 class App: Application() {
 
     companion object {

sampleapp/src/main/java/io/matthewnelson/sampleapp/LogMessageAdapter.kt

@@ -25,6 +25,9 @@ import androidx.lifecycle.Observer
 import androidx.recyclerview.widget.LinearLayoutManager
 import androidx.recyclerview.widget.RecyclerView
 
+/**
+ * @suppress
+ * */
 class LogMessageAdapter(
     activity: MainActivity
 ): RecyclerView.Adapter<LogMessageAdapter.LogMessageHolder>(){

sampleapp/src/main/java/io/matthewnelson/sampleapp/MainActivity.kt

@@ -25,6 +25,9 @@ import io.matthewnelson.topl_service.TorServiceController
 import io.matthewnelson.topl_service.util.ServiceConsts.PrefKeyBoolean
 import io.matthewnelson.topl_service.prefs.TorServicePrefs
 
+/**
+ * @suppress
+ * */
 class MainActivity : AppCompatActivity() {
 
     private companion object {

sampleapp/src/main/java/io/matthewnelson/sampleapp/MyEventBroadcaster.kt

@@ -21,6 +21,9 @@ import androidx.lifecycle.MutableLiveData
 import io.matthewnelson.topl_core_base.EventBroadcaster
 import io.matthewnelson.topl_service.util.ServiceUtilities
 
+/**
+ * @suppress
+ * */
 class MyEventBroadcaster: EventBroadcaster() {
 
 

sampleapp/src/main/java/io/matthewnelson/sampleapp/MyTorSettings.kt

@@ -20,6 +20,7 @@ import io.matthewnelson.topl_core_base.TorSettings
 
 /**
  * See [TorSettings] for comments on what is what.
+ * @suppress
  * */
 class MyTorSettings: TorSettings() {
 

sampleapp/src/main/java/io/matthewnelson/sampleapp/samplecode/SampleCode.kt

@@ -0,0 +1,95 @@
+package io.matthewnelson.sampleapp.samplecode
+
+import android.app.Application
+import android.content.Context
+import androidx.core.app.NotificationCompat
+import io.matthewnelson.sampleapp.App
+import io.matthewnelson.sampleapp.BuildConfig
+import io.matthewnelson.sampleapp.MainActivity
+import io.matthewnelson.sampleapp.R
+import io.matthewnelson.topl_core_base.EventBroadcaster
+import io.matthewnelson.topl_core_base.TorConfigFiles
+import io.matthewnelson.topl_service.TorServiceController
+import java.io.File
+
+/**
+ * This class is for sample code that is to be used while creating Dokka Docs/MkDocs.
+ * @suppress
+ * */
+object SampleCode {
+
+    /**
+     * Contains all possible options for initializing [TorServiceController.Builder]
+     * */
+    fun setupTorServices(
+        application: Application,
+        eventBroadcaster: EventBroadcaster,
+        torConfigFiles: TorConfigFiles
+    ) {
+
+        TorServiceController.Builder(
+            application = application,
+            buildConfigVersionCode = BuildConfig.VERSION_CODE,
+            torSettings = App.myTorSettings,
+
+            // These should live somewhere in your project application's assets directory
+            geoipAssetPath = "common/geoip",
+            geoip6AssetPath = "common/geoip6"
+        )
+
+            .setBuildConfigDebug(BuildConfig.DEBUG)
+            .setEventBroadcaster(eventBroadcaster)
+            .useCustomTorConfigFiles(torConfigFiles)
+
+            // Notification customization
+            .customizeNotification(
+                channelName = "TorService Channel",
+                channelDescription = "Tor Channel",
+                channelID = "My Sample Application",
+                notificationID = 615
+            )
+            .setActivityToBeOpenedOnTap(
+                clazz = MainActivity::class.java,
+                intentExtrasKey = null,
+                intentExtras = null,
+                intentRequestCode = null
+            )
+            .setImageTorNetworkingEnabled(R.drawable.tor_stat_network_enabled)
+            .setImageTorNetworkingDisabled(R.drawable.tor_stat_network_disabled)
+            .setImageTorDataTransfer(R.drawable.tor_stat_network_dataxfer)
+            .setImageTorErrors(R.drawable.tor_stat_notifyerr)
+            .setCustomColor(R.color.tor_service_white, colorizeBackground = true)
+            .setVisibility(NotificationCompat.VISIBILITY_PRIVATE)
+            .enableTorRestartButton(enable = true)
+            .enableTorStopButton(enable = true)
+
+            // Will return a Builder object to continue with non-notification related options
+            .applyNotificationSettings()
+
+            .build()
+    }
+
+    private fun customTorConfigFilesSetup(context: Context): TorConfigFiles {
+        // This is modifying the directory hierarchy from TorService's
+        // default setup. For example, if you are using binaries for Tor that
+        // are named differently that that expressed in TorConfigFiles.createConfig()
+
+        // Post Android API 28 requires that executable files be contained in your
+        // application's data/app directory, as they can no longer execute from data/data.
+        val installDir = File(context.applicationInfo.nativeLibraryDir)
+
+        // Will create a directory within your application's data/data dir
+        val configDir = context.getDir("torservice", Context.MODE_PRIVATE)
+
+        val builder = TorConfigFiles.Builder(installDir, configDir)
+
+        // Customize the tor executable file name. Requires that the executable file
+        // be in your project's src/main/jniLibs directory. If you are getting your
+        // executable files via a dependency, be sure to consult that Libraries documentation.
+        builder.torExecutable(File(installDir, "libtor.so"))
+
+        // customize further via the builder methods...
+
+        return builder.build()
+    }
+}

topl-core-base/build.gradle

@@ -1,6 +1,7 @@
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 apply plugin: 'kotlin-android-extensions'
+apply plugin: 'org.jetbrains.dokka'
 
 android {
     compileSdkVersion versions.compileSdk
@@ -34,6 +35,17 @@ android {
     }
 }
 
+dokka {
+    configuration {
+        reportUndocumented = false
+        includeNonPublic = false
+        skipEmptyPackages = true
+        samples = [
+                "$rootDir/sampleapp/samplecode/SampleCode.kt".toString()
+        ]
+    }
+}
+
 dependencies {
     implementation fileTree(dir: "libs", include: ["*.jar"])
     implementation deps.kotlin.stdlib

topl-core-base/src/main/java/io/matthewnelson/topl_core_base/TorConfigFiles.kt

@@ -181,6 +181,7 @@ class TorConfigFiles private constructor(
      *
      * @param [installDir] directory where the tor binaries are installed.
      * @param [configDir] directory where the filesystem will be setup for tor.
+     * @sample [io.matthewnelson.sampleapp.samplecode.SampleCode.customTorConfigFilesSetup]
      */
     class Builder(private val installDir: File, private val configDir: File) {
 

topl-core-base/src/main/java/io/matthewnelson/topl_core_base/TorSettings.kt

@@ -57,8 +57,6 @@ package io.matthewnelson.topl_core_base
  *
  * Would **highly recommend** reading up on what's what:
  *  - See <a href="https://2019.www.torproject.org/docs/tor-manual.html.en" target="_blank">docs</a>
- *
- * @sample [io.matthewnelson.sampleapp.MyTorSettings]
  * */
 abstract class TorSettings: BaseConsts() {
 

topl-core/build.gradle

@@ -1,6 +1,7 @@
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 apply plugin: 'kotlin-android-extensions'
+apply plugin: 'org.jetbrains.dokka'
 
 android {
     compileSdkVersion versions.compileSdk
@@ -34,6 +35,18 @@ android {
     }
 }
 
+dokka {
+    configuration {
+        reportUndocumented = false
+        includeNonPublic = false
+        skipEmptyPackages = true
+        samples = [
+                "$rootDir/topl-service/service/TorService.kt".toString(),
+                "$rootDir/topl-service/service/onionproxy/ServiceTorInstaller.kt".toString()
+        ]
+    }
+}
+
 dependencies {
     implementation fileTree(dir: "libs", include: ["*.jar"])
     implementation project(':topl-core-base')

topl-core/src/main/java/io/matthewnelson/topl_core/OnionProxyManager.kt

@@ -86,6 +86,7 @@ import java.util.concurrent.TimeUnit
  * @param [buildConfigDebug] Send [BuildConfig.DEBUG] which will show Logcat messages for this
  *   module on Debug builds of your Application. If `null`, all the messages will still be
  *   broadcast to the provided [EventBroadcaster] and you can handle them there how you'd like.
+ * @sample [io.matthewnelson.topl_service.service.TorService.initTOPLCore]
  * */
 class OnionProxyManager(
     private val context: Context,
@@ -853,7 +854,7 @@ class OnionProxyManager(
         eventListener.beginWatchingNoticeMsgs()
 
         val signalSuccess = signalControlConnection(TorControlCommands.SIGNAL_NEWNYM)
-        val rateLimited = eventListener.doesNoticeMsgBufferContain(NEWNYM_RATE_LIMIT_PARTIAL_MSG)
+        val rateLimited = eventListener.doesNoticeMsgBufferContain(NEWNYM_RATE_LIMIT_PARTIAL_MSG, 50L)
 
         if (signalSuccess) {
             if (!rateLimited) {

topl-core/src/main/java/io/matthewnelson/topl_core/listener/BaseEventListener.kt

@@ -47,12 +47,6 @@ abstract class BaseEventListener: EventListener() {
      * See [TorControlCommands.EVENT_NAMES] values. These are **REQUIRED**
      * for registering them in [io.matthewnelson.topl_core.OnionProxyManager.start]
      * which allows you full control over what you wish to listen for.
-     *
-     * WARNING: Be careful as to what events your are attempting to listen for. If
-     * jtorctl has not implemented that event yet it will crash.
-     *
-     * See <a href="https://github.com/05nelsonm/TorOnionProxyLibrary-Android/issues/14" target="_blank">this issue</a>
-     * for more details.
      * */
     abstract val CONTROL_COMMAND_EVENTS: Array<String>
 
@@ -72,17 +66,24 @@ abstract class BaseEventListener: EventListener() {
         delay(50)
     }
 
-    internal suspend fun doesNoticeMsgBufferContain(string: String): Boolean {
-        delay(50)
+    /**
+     * Checks [noticeMsgBuffer] for the declared [string] and resets [noticeMsgBuffer] to null.
+     *
+     * @param [string] The string you wish to check for in [noticeMsgBuffer]
+     * @param [delayMilliseconds] Length of time you wish to delay the coroutine for before executing
+     * @return True if it contains the string, false if not.
+     * */
+    internal suspend fun doesNoticeMsgBufferContain(string: String, delayMilliseconds: Long): Boolean {
+        delay(delayMilliseconds)
         val boolean = noticeMsgBuffer.toString().contains(string)
         noticeMsgBuffer = null
         return boolean
     }
 
     /**
      * Requires that when you extend this class and override [noticeMsg], you **must**
-     * use `super.noticeMsg(data)` within your override; otherwise, it will never get
-     * messages to watch for the string value.
+     * use `super.noticeMsg(data)` within your overridden method; otherwise, [noticeMsgBuffer]
+     * [beginWatchingNoticeMsgs] and [doesNoticeMsgBufferContain] will not work correctly.
      * */
     override fun noticeMsg(data: String?) {
         noticeMsgBuffer?.append("${data}\n")

topl-core/src/main/java/io/matthewnelson/topl_core/settings/TorSettingsBuilder.kt

@@ -74,6 +74,7 @@ import java.util.*
  *
  * @param [onionProxyContext] [OnionProxyContext]
  * @param [broadcastLogger] for broadcasting/logging
+ * @sample [io.matthewnelson.topl_service.service.TorService.generateTorrcFile]
  * */
 class TorSettingsBuilder internal constructor(
     private val onionProxyContext: OnionProxyContext,

topl-core/src/main/java/io/matthewnelson/topl_core/util/TorInstaller.kt

@@ -49,6 +49,14 @@ import java.io.IOException
 import java.io.InputStream
 import java.util.concurrent.TimeoutException
 
+/**
+ * Extend this class and implement the need methods.
+ *
+ * [setup] is called from [io.matthewnelson.topl_core.OnionProxyManager.setup] after
+ * instantiation, and [openBridgesStream] is called from
+ * [io.matthewnelson.topl_core.settings.TorSettingsBuilder.addBridgesFromResources]
+ * when configuring bridge support.
+ * */
 abstract class TorInstaller: CoreConsts() {
 
     /**
@@ -67,6 +75,7 @@ abstract class TorInstaller: CoreConsts() {
      * the system this does not need to be invoked.
      *
      * @return true if tor installation is successful, otherwise false.
+     * @sample [io.matthewnelson.topl_service.onionproxy.ServiceTorInstaller.setup]
      */
     @Throws(IOException::class)
     abstract fun setup()
@@ -88,6 +97,8 @@ abstract class TorInstaller: CoreConsts() {
      * `($bridge_info \r\n)*`
      *
      * The second form is used for custom bridges from the user.
+     *
+     * @sample [io.matthewnelson.topl_service.onionproxy.ServiceTorInstaller.openBridgesStream]
      */
     @Throws(IOException::class)
     abstract fun openBridgesStream(): InputStream?

topl-service/build.gradle

@@ -1,6 +1,7 @@
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 apply plugin: 'kotlin-android-extensions'
+apply plugin: 'org.jetbrains.dokka'
 
 android {
     compileSdkVersion versions.compileSdk
@@ -34,6 +35,17 @@ android {
     }
 }
 
+dokka {
+    configuration {
+        reportUndocumented = false
+        includeNonPublic = false
+        skipEmptyPackages = true
+        samples = [
+                "$rootDir/sampleapp/samplecode/SampleCode.kt".toString()
+        ]
+    }
+}
+
 dependencies {
     implementation fileTree(dir: "libs", include: ["*.jar"])
     implementation project(':topl-core')

topl-service/src/main/java/io/matthewnelson/topl_service/TorServiceController.kt

@@ -65,7 +65,7 @@ class TorServiceController private constructor(): ServiceConsts() {
      * @param [geoip6AssetPath] The path to where you have your geoip6 file located (ex: in
      *   assets/common directory, send this variable "common/geoip6").
      *
-     * @sample [io.matthewnelson.sampleapp.App.setupTorServices]
+     * @sample [io.matthewnelson.sampleapp.samplecode.SampleCode.setupTorServices]
      * */
     class Builder(
         private val application: Application,
@@ -122,9 +122,8 @@ class TorServiceController private constructor(): ServiceConsts() {
          * [Context.getApplicationContext] to set up a standard directory hierarchy for Tor
          * to operate with.
          *
-         * See [Builder] for code samples.
-         *
          * @return [Builder]
+         * @sample [io.matthewnelson.sampleapp.samplecode.SampleCode.customTorConfigFilesSetup]
          * @see [Builder.build]
          * */
         fun useCustomTorConfigFiles(torConfigFiles: TorConfigFiles): Builder {
@@ -141,7 +140,8 @@ class TorServiceController private constructor(): ServiceConsts() {
          * @param [channelID] Your notification channel's ID (cannot be empty).
          * @param [channelDescription] Your notification channel's description (cannot be empty).
          * @param [notificationID] Your foreground notification's ID.
-         * @return [NotificationBuilder] to obtain methods specific to notification customization.
+         * @return [NotificationBuilder] To obtain methods specific to notification customization.
+         * @throws [IllegalArgumentException] If String fields are empty.
          * */
         @Throws(IllegalArgumentException::class)
         fun customizeNotification(