diff --git a/.circleci/config.yml b/.circleci/config.yml index 48ff6dd4..7bd4ae7f 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -158,6 +158,20 @@ jobs: command: ./gradlew incrementVersion - save_cache: *save_cache-gradle + publish-docs: + <<: *build-defaults + resource_class: large + steps: + - checkout + - attach_workspace: + at: *workspace + - restore_cache: *restore_cache-gradle + - run: *configure-git-user + - run: + name: Publish Docs + command: ./gradlew publishDocs + - save_cache: *save_cache-gradle + workflows: build-test-publish: jobs: @@ -187,7 +201,11 @@ workflows: jobs: - publish-release: <<: *release-filter - - bump-version: + - publish-docs: <<: *release-filter requires: - publish-release + - bump-version: + <<: *release-filter + requires: + - publish-docs diff --git a/CHANGELOG.md b/CHANGELOG.md index e6009a81..b57318e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +### 1.1.1 + +Enhancements + +- Added public KDoc documentation for each release. The latest documentation release can be found at https://twilio.github.io/audioswitch/latest + ### 1.1.0 Enhancements diff --git a/README.md b/README.md index 36df58ba..c3a3f176 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,10 @@ Android Studio Version | Android API Version Min ------------ | ------------- 3.6+ | 16 +## Documentation + +The KDoc for this library can be found [here](https://twilio.github.io/audioswitch/latest). + ## Getting Started To get started using this library, follow the steps below. diff --git a/audioswitch/build.gradle b/audioswitch/build.gradle index d597fd4a..14e89f07 100644 --- a/audioswitch/build.gradle +++ b/audioswitch/build.gradle @@ -3,6 +3,7 @@ apply plugin: 'maven' apply plugin: 'maven-publish' apply plugin: "com.jfrog.artifactory" apply plugin: 'kotlin-android' +apply plugin: "org.jetbrains.dokka" android { compileSdkVersion 30 @@ -37,6 +38,16 @@ android { } } + dokkaHtml.configure { + dokkaSourceSets { + named("main") { + noAndroidSdkLink.set(false) + includeNonPublic = false + reportUndocumented = true + skipEmptyPackages = true + } + } + } } dependencies { diff --git a/audioswitch/index.html b/audioswitch/index.html new file mode 100644 index 00000000..cd5e2217 --- /dev/null +++ b/audioswitch/index.html @@ -0,0 +1,13 @@ + + + + + + Document + + + + + \ No newline at end of file diff --git a/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt b/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt index 41fe5f6f..e92b588d 100644 --- a/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt +++ b/audioswitch/src/main/java/com/twilio/audioswitch/AudioDeviceChangeListener.kt @@ -1,11 +1,10 @@ package com.twilio.audioswitch -/** A listener that receives the most recently available [AudioDevice]s. +/** * Receives a list of the most recently available [AudioDevice]s. Also provides the * currently selected [AudioDevice] from [AudioSwitch]. - * - * @param audioDevices the list of [AudioDevice]s or an empty list if none are available. - * @param selectedAudioDevice the currently selected device or null if no device has been selected. + * - audioDevices - The list of [AudioDevice]s or an empty list if none are available. + * - selectedAudioDevice - The currently selected device or null if no device has been selected. */ typealias AudioDeviceChangeListener = ( audioDevices: List, diff --git a/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt b/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt index a21b6918..c95415a2 100644 --- a/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt +++ b/audioswitch/src/main/java/com/twilio/audioswitch/AudioSwitch.kt @@ -26,7 +26,12 @@ private const val TAG = "AudioSwitch" * should be routed to. It is strongly recommended that instances of this class are created and * accessed from a single application thread. Accessing an instance from multiple threads may cause * synchronization problems. - */ + * + * @property loggingEnabled A property to configure AudioSwitch logging behavior. AudioSwitch logging is disabled by + * default. + * @property selectedAudioDevice Retrieves the selected [AudioDevice] from [AudioSwitch.selectDevice]. + * @property availableAudioDevices Retrieves the current list of available [AudioDevice]s. +**/ class AudioSwitch { private var logger: Logger = ProductionLogger() @@ -67,58 +72,30 @@ class AudioSwitch { } } - /** - * A property to configure AudioSwitch logging behavior. AudioSwitch logging is disabled by - * default. - */ var loggingEnabled: Boolean - /** - * Returns `true` if logging is enabled. Returns `false` by default. - */ get() = logger.loggingEnabled - /** - * Toggle whether logging is enabled. - */ set(value) { logger.loggingEnabled = value } - - /** - * Retrieves the selected [AudioDevice] from [AudioSwitch.selectDevice]. - * - * @return the selected [AudioDevice] - */ val selectedAudioDevice: AudioDevice? get() = selectedDevice - - /** - * Retrieves the current list of available [AudioDevice]s. - * - * @return the current list of [AudioDevice]s - */ val availableAudioDevices: List = mutableAudioDevices /** * Constructs a new AudioSwitch instance. - * - * @param context An Android Context. - * @param loggingEnabled Toggle whether logging is enabled. This argument is false by default. - * @param audioFocusChangeListener A listener that is invoked when the system audio focus is updated. + * - [context] - An Android Context. + * - [loggingEnabled] - Toggle whether logging is enabled. This argument is false by default. + * - [audioFocusChangeListener] - A listener that is invoked when the system audio focus is updated. * Note that updates are only sent to the listener after [activate] has been called. - * @param preferredDeviceList The order in which [AudioSwitch] automatically selects and activates + * - [preferredDeviceList] - The order in which [AudioSwitch] automatically selects and activates * an [AudioDevice]. This parameter is ignored if the [selectedAudioDevice] is not `null`. - * * The default preferred [AudioDevice] order is the following: - * * [BluetoothHeadset], [WiredHeadset], [Earpiece], [Speakerphone] - * - * [preferredDeviceList] is added to the front of the default list. For example, if [preferredDeviceList] + * . The [preferredDeviceList] is added to the front of the default list. For example, if [preferredDeviceList] * is [Speakerphone] and [BluetoothHeadset], then the new preferred audio * device list will be: - * * [Speakerphone], [BluetoothHeadset], [WiredHeadset], [Earpiece]. - * - * @throws IllegalArgumentException if the [preferredDeviceList] contains duplicate [AudioDevice] elements. + * An [IllegalArgumentException] is thrown if the [preferredDeviceList] contains duplicate [AudioDevice] elements. */ @JvmOverloads constructor( @@ -171,11 +148,9 @@ class AudioSwitch { } /** - * Starts listening for audio device changes. **Note:** When audio device listening is no - * longer needed, [AudioSwitch.stop] should be called in order to prevent a - * memory leak. - * - * @param listener receives audio device change events + * Starts listening for audio device changes and calls the [listener] upon each change. + * **Note:** When audio device listening is no longer needed, [AudioSwitch.stop] should be + * called in order to prevent a memory leak. */ fun start(listener: AudioDeviceChangeListener) { audioDeviceChangeListener = listener @@ -253,11 +228,10 @@ class AudioSwitch { } /** - * Selects the desired [AudioDevice]. If the provided [AudioDevice] is not - * available, no changes are made. If the provided [AudioDevice] is null, an [AudioDevice] is - * chosen based on the following preference: Bluetooth, Wired Headset, Earpiece, Speakerphone. - * - * @param audioDevice The [AudioDevice] to use + * Selects the desired [audioDevice]. If the provided [AudioDevice] is not + * available, no changes are made. If the provided device is null, one is chosen based on the + * specified preferred device list or the following default list: + * [BluetoothHeadset], [WiredHeadset], [Earpiece], [Speakerphone]. */ fun selectDevice(audioDevice: AudioDevice?) { if (selectedDevice != audioDevice) { diff --git a/build.gradle b/build.gradle index f4d097e3..25760da1 100644 --- a/build.gradle +++ b/build.gradle @@ -1,5 +1,6 @@ buildscript { ext.kotlin_version = '1.4.0' + ext.dokka_version = '1.4.10' /** * Properties and environment variables needed to publish to Bintray. @@ -74,17 +75,20 @@ buildscript { dependencies { classpath 'com.android.tools.build:gradle:4.0.0' classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" + classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version" } } plugins { id "com.diffplug.spotless" version "5.6.1" id "com.jfrog.artifactory" version "4.15.2" + id "org.jetbrains.dokka" version "1.4.10" } apply plugin: "com.diffplug.spotless" spotless { format 'misc', { target '**/*.gradle', '**/*.md', '**/.gitignore' + targetExclude 'docs/**' trimTrailingWhitespace() indentWithSpaces() @@ -238,3 +242,85 @@ task bintrayAudioSwitchReleaseUpload(type: RootGradleBuild) { 'maven.password': "${getPropertyValue("AUDIOSWITCH_BINTRAY_PASSWORD")}" ] } + +task publishDocs { + description = 'Publish AudioSwitch KDocs to gh-pages branch' + group = 'Publishing' + dependsOn 'audioswitch:dokkaHtml' + dependsOn validateReleaseTag + def releaseVersion = System.getenv("CIRCLE_TAG") == null ? + ("") : + (System.getenv("CIRCLE_TAG")) + def pinLatestDocsCommand = ["ln", "-sfn", "${releaseVersion}", "docs/latest"] + def githubToken = System.getenv("GITHUB_TOKEN") + def repoSlug = "${System.env.CIRCLE_PROJECT_USERNAME}/${System.env.CIRCLE_PROJECT_REPONAME}" + def gitRef = "https://${githubToken}@github.com/${repoSlug}.git" + def remote = "upstream" + def pushNullFile = new FileOutputStream("/dev/null") + + doLast { + exec { + workingDir "${rootDir}" + commandLine "cp", "audioswitch/index.html", "audioswitch/build" + } + + exec { + workingDir "${rootDir}" + commandLine "git", "remote", "add", "${remote}", "${gitRef}" + // Ignore exit value because remote may have been added in previous task + ignoreExitValue true + } + + exec { + workingDir "${rootDir}" + commandLine "git", "fetch", "${remote}" + } + + exec { + workingDir "${rootDir}" + commandLine "git", "checkout", "-b", "gh-pages", "remotes/${remote}/gh-pages" + } + + exec { + workingDir "${rootDir}" + commandLine "mkdir", "docs" + ignoreExitValue true + } + + exec { + workingDir "${rootDir}" + commandLine "cp", "-r", "audioswitch/build/dokka/html/.", "docs/${releaseVersion}" + } + + exec { + workingDir "${rootDir}" + commandLine "cp", "audioswitch/build/index.html", "docs/${releaseVersion}" + } + + exec { + workingDir "${rootDir}" + commandLine pinLatestDocsCommand + } + + exec { + workingDir "${rootDir}" + commandLine "git", "add", "docs/${releaseVersion}", "docs/latest" + } + + exec { + workingDir "${rootDir}" + commandLine "git", "commit", "-m", "\"${releaseVersion} release docs [skip ci]\"" + } + + exec { + workingDir "${rootDir}" + commandLine "git", "push", "--quiet", "${remote}", "gh-pages" + standardOutput pushNullFile + } + + exec { + workingDir "${rootDir}" + commandLine "git", "checkout", "${releaseVersion}" + } + } +}