Generate docs (#480)

.github/workflows/blank.yml → .github/workflows/ci.yml

@@ -1,12 +1,12 @@
-# This is a basic workflow to help you get started with Actions
-
+# Default Skiko CI
 name: CI
 
 # Controls when the action will run.
 on:
   # Triggers the workflow on push or pull request events but only for the master branch
   push:
     branches: [ master ]
+  # TODO: temporary for faster tests, restore!
   pull_request:
     branches: [ master ]
 
@@ -160,3 +160,4 @@ jobs:
           name: test-reports-windows
           path: ./skiko/build/reports/tests
           retention-days: 5
+

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+# Build Skiko documentation
+name: Doc
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master ]
+  # Temporary, for testing. Remove!
+  #pull_request:
+  #  branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# See https://github.com/marketplace/actions/deploy-to-github-pages
+jobs:
+  dokka:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-java@v2
+        with:
+          distribution: 'adopt'
+          java-version: '11'
+      - name: Build docs
+        run: bash -c 'JAVA_OPTS="-Xmx4g" ./gradlew --no-daemon  -Pskiko.native.enabled=true -Pskiko.wasm.enabled=true -Pskiko.android.enabled=true :skiko:dokkaHtml'
+      - name: Publish documentation
+        uses: JamesIves/github-pages-deploy-action@releases/v3
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: ./skiko/build/dokka/html

skiko/build.gradle.kts

@@ -9,6 +9,7 @@ import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 
 plugins {
     kotlin("multiplatform") version "1.6.10"
+    id("org.jetbrains.dokka") version "1.6.10"
     `maven-publish`
     signing
     id("org.gradle.crypto.checksum") version "1.1.0"

skiko/src/awtMain/kotlin/org/jetbrains/skiko/SkiaLayer.awt.kt

@@ -22,7 +22,7 @@ actual open class SkiaLayer internal constructor(
     private val renderFactory: RenderFactory = RenderFactory.Default
 ) : JPanel() {
 
-    companion object {
+    internal companion object {
         init {
             Library.load()
         }
@@ -527,10 +527,16 @@ actual open class SkiaLayer internal constructor(
     }
 }
 
+/**
+ * Disable showing window title bar.
+ */
 fun SkiaLayer.disableTitleBar(customHeaderHeight: Float) {
     backedLayer.disableTitleBar(customHeaderHeight)
 }
 
+/**
+ * Request to show emoji and symbols popup.
+ */
 fun orderEmojiAndSymbolsPopup() {
     platformOperations.orderEmojiAndSymbolsPopup()
 }

skiko/src/commonMain/kotlin/org/jetbrains/skia/AnimationDisposalMethod.kt

@@ -8,7 +8,10 @@ package org.jetbrains.skia
  * Names are based on the GIF 89a spec.
  */
 enum class AnimationDisposalMethod {
-    _UNUSED,
+    /**
+     * Do not use
+     */
+    UNUSED,
 
     /**
      *

skiko/src/commonMain/kotlin/org/jetbrains/skia/AnimationDisposalMode.kt

@@ -8,7 +8,10 @@ package org.jetbrains.skia
  * Names are based on the GIF 89a spec.
  */
 enum class AnimationDisposalMode {
-    _UNUSED,
+    /**
+     * Do not use
+     */
+    UNUSED,
 
     /**
      *

skiko/src/commonMain/kotlin/org/jetbrains/skia/ColorInfo.kt

@@ -46,11 +46,11 @@ class ColorInfo(val colorType: ColorType, val alphaType: ColorAlphaType, val col
     }
 
     override fun hashCode(): Int {
-        val PRIME = 59
+        val prime = 59
         var result = 1
-        result = result * PRIME + colorType.hashCode()
-        result = result * PRIME + alphaType.hashCode()
-        result = result * PRIME + colorSpace.hashCode()
+        result = result * prime + colorType.hashCode()
+        result = result * prime + alphaType.hashCode()
+        result = result * prime + colorSpace.hashCode()
         return result
     }
 

skiko/src/commonMain/kotlin/org/jetbrains/skia/Data.kt

@@ -87,14 +87,14 @@ class Data internal constructor(ptr: NativePointer) : Managed(ptr, _FinalizerHol
 
     override fun equals(other: Any?): Boolean {
         val otherData = other as? Data ?: return false
-        return _nativeEquals(otherData)
+        return nativeEquals(otherData)
     }
 
     /**
      * Returns true if these two objects have the same length and contents,
      * effectively returning 0 == memcmp(...)
      */
-    override fun _nativeEquals(other: Native?): Boolean {
+    override fun nativeEquals(other: Native?): Boolean {
         return try {
             Stats.onNativeCall()
             _nEquals(_ptr, getPtr(other))

skiko/src/commonMain/kotlin/org/jetbrains/skia/EncodedOrigin.kt

@@ -1,7 +1,10 @@
 package org.jetbrains.skia
 
 enum class EncodedOrigin {
-    _UNUSED,
+    /**
+     * Do not use
+     */
+    UNUSED,
 
     /**
      * Default

skiko/src/commonMain/kotlin/org/jetbrains/skia/Expects.kt

@@ -1,10 +1,10 @@
 package org.jetbrains.skia
 
-expect fun <R> commonSynchronized(lock: Any, block: () -> R)
+internal expect fun <R> commonSynchronized(lock: Any, block: () -> R)
 
-expect fun String.intCodePoints(): IntArray
+internal expect fun String.intCodePoints(): IntArray
 
-expect fun defaultLanguageTag(): String
+internal expect fun defaultLanguageTag(): String
 
 expect abstract class OutputStream
 
@@ -19,7 +19,7 @@ expect class Matcher {
     fun matches(): Boolean
 }
 
-expect fun compilePattern(regex: String): Pattern
+internal expect fun compilePattern(regex: String): Pattern
 
 @OptIn(ExperimentalMultiplatform::class)
 @OptionalExpectation

skiko/src/commonMain/kotlin/org/jetbrains/skia/Font.kt

@@ -77,7 +77,7 @@ class Font : Managed {
      * Compares fonts, and returns true if they are equivalent.
      * May return false if Typeface has identical contents but different pointers.
      */
-    override fun _nativeEquals(other: Native?): Boolean {
+    override fun nativeEquals(other: Native?): Boolean {
         return try {
             Font_nEquals(_ptr, getPtr(other))
         } finally {

skiko/src/commonMain/kotlin/org/jetbrains/skia/ImageFilter.kt

@@ -659,7 +659,7 @@ private external fun _nMakeArithmetic(
     enforcePMColor: Boolean,
     bg: NativePointer,
     fg: NativePointer,
-    crop: InteropPointer?
+    crop: InteropPointer
 ): NativePointer
 
 @ExternalSymbolName("org_jetbrains_skia_ImageFilter__1nMakeBlend")

skiko/src/commonMain/kotlin/org/jetbrains/skia/Paint.kt

@@ -49,7 +49,7 @@ class Paint : Managed {
         }
     }
 
-    override fun _nativeEquals(other: Native?): Boolean {
+    override fun nativeEquals(other: Native?): Boolean {
         return try {
             Paint_nEquals(_ptr, getPtr(other))
         } finally {

skiko/src/commonMain/kotlin/org/jetbrains/skia/Path.kt

@@ -239,7 +239,7 @@ class Path internal constructor(ptr: NativePointer) : Managed(ptr, _FinalizerHol
      * @param other  Path to compare
      * @return   true if this and Path are equivalent
      */
-    override fun _nativeEquals(other: Native?): Boolean {
+    override fun nativeEquals(other: Native?): Boolean {
         return try {
             Path_nEquals(_ptr, getPtr(other))
         } finally {

skiko/src/commonMain/kotlin/org/jetbrains/skia/StdVectorDecoder.kt

@@ -25,7 +25,7 @@ class ArrayDecoder(private val ptr: NativePointer, private val disposePtr: Nativ
         get() = StdVectorDecoder_nGetArraySize(ptr)
 }
 
-inline fun <T> arrayDecoderScope(arrayDecoderBlock: () -> ArrayDecoder, block: (arrayCode: ArrayDecoder) -> T): T {
+internal inline fun <T> arrayDecoderScope(arrayDecoderBlock: () -> ArrayDecoder, block: (arrayCode: ArrayDecoder) -> T): T {
     var arrayDecoder: ArrayDecoder? = null
     return try {
         arrayDecoder = arrayDecoderBlock()

skiko/src/commonMain/kotlin/org/jetbrains/skia/Typeface.kt

@@ -155,7 +155,7 @@ class Typeface internal constructor(ptr: NativePointer) : RefCnt(ptr) {
     /**
      * @return  true if the two typefaces reference the same underlying font, treating null as the default font
      */
-    override fun _nativeEquals(other: Native?): Boolean {
+    override fun nativeEquals(other: Native?): Boolean {
         return try {
             Typeface_nEquals(_ptr, getPtr(other))
         } finally {

skiko/src/commonMain/kotlin/org/jetbrains/skia/impl/Library.kt

@@ -1,5 +1,8 @@
 package org.jetbrains.skia.impl
 
+/**
+ * Object representing native library containing non-Kotlin part of Skiko.
+ */
 expect class Library {
     companion object {
         fun staticLoad()

skiko/src/commonMain/kotlin/org/jetbrains/skia/impl/Managed.kt

@@ -1,10 +1,23 @@
 package org.jetbrains.skia.impl
 
+/**
+ * Peer for a native object.
+ */
 expect abstract class Managed(ptr: NativePointer, finalizer: NativePointer, managed: Boolean = true) : Native {
+    /**
+     * Free underlying native resource, peer is useless afterwards.
+     */
     open fun close()
+
+    /**
+     * Check if underlying resource is closed.
+     */
     open val isClosed: Boolean
 }
 
+/**
+ * Utility function to use managed object and them immediately release it.
+ */
 inline fun <T: Managed, R> T.use(block: (T) -> R): R {
     return try {
         block(this)