add docs 1..15 (#489)

* add docs 1..15

* docs 1..15 improvements
Co-authored-by: Oleksandr Karpovich <oleksandr.karpovich@jetbrains.com>

skiko/src/jsMain/kotlin/org/jetbrains/skiko/SkiaLayer.js.kt

@@ -60,6 +60,9 @@ actual open class SkiaLayer {
      */
     actual var skikoView: SkikoView? = null
 
+    /**
+     * @param container - should be an instance of [HTMLCanvasElement]
+     */
     actual fun attachTo(container: Any) {
         attachTo(container as HTMLCanvasElement, false)
     }

skiko/src/jsTest/kotlin/TestUtils.js.kt

 package org.jetbrains.skiko.tests
 
-import kotlinx.coroutines.GlobalScope
+import kotlinx.coroutines.MainScope
 import kotlinx.coroutines.promise
 import org.jetbrains.skia.Data
 import org.jetbrains.skia.impl.InteropScope
 import org.jetbrains.skia.impl.NativePointer
-import org.jetbrains.skiko.wasm.await
 import org.jetbrains.skiko.wasm.wasmSetup
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlin.coroutines.suspendCoroutine
+import kotlin.js.Promise
 
-actual fun runTest(block: suspend () -> Unit): dynamic = GlobalScope.promise {
+private suspend fun <T> Promise<T>.await(): T = suspendCoroutine { cont ->
+    then({ cont.resume(it) }, { cont.resumeWithException(it) })
+}
+
+/**
+ * Awaits for `wasmSetup` and then runs the [block] in a coroutine.
+ */
+actual fun runTest(block: suspend () -> Unit): dynamic = MainScope().promise {
     wasmSetup.await()
     block()
 }

skiko/src/jsTest/kotlin/WasmTests.kt

-package org.jetbrains.skiko.wasm
-
-import kotlinx.coroutines.GlobalScope
-import kotlinx.coroutines.promise
-import kotlin.coroutines.*
-import kotlin.js.Promise
-
-external interface ModuleInterface
-external val Module: ModuleInterface
-
-suspend fun <T> Promise<T>.await(): T = suspendCoroutine { cont ->
-    then({ cont.resume(it) }, { cont.resumeWithException(it) })
-}
-
-internal fun wasmTest(block: () -> Unit) = GlobalScope.promise {
-    wasmSetup.await()
-    block.invoke()
-}
-
-class WasmTests

skiko/src/macosMain/kotlin/org/jetbrains/skiko/RenderFactory.macos.kt

 package org.jetbrains.skiko
 
-import org.jetbrains.skiko.context.ContextHandler
-import org.jetbrains.skiko.redrawer.MacOsOpenGLRedrawer
 import org.jetbrains.skiko.redrawer.MacOsMetalRedrawer
+import org.jetbrains.skiko.redrawer.MacOsOpenGLRedrawer
 import org.jetbrains.skiko.redrawer.Redrawer
 
+/**
+ * Creates an instance of [Redrawer] using [renderApi].
+ * Valid values for [renderApi] are: [GraphicsApi.OPENGL], [GraphicsApi.METAL].
+ * If [renderApi] is not one of the valid, then throws IllegalArgumentException.
+ */
 internal fun createNativeRedrawer(
     layer: SkiaLayer,
     renderApi: GraphicsApi
@@ -12,4 +16,4 @@ internal fun createNativeRedrawer(
     GraphicsApi.OPENGL -> MacOsOpenGLRedrawer(layer)
     GraphicsApi.METAL -> MacOsMetalRedrawer(layer)
     else -> throw IllegalArgumentException("Unsupported API $renderApi")
-}
\ No newline at end of file
+}

skiko/src/macosMain/kotlin/org/jetbrains/skiko/SkiaLayer.macos.kt

@@ -25,39 +25,82 @@ import platform.Foundation.addObserver
 import platform.darwin.NSObject
 import platform.CoreGraphics.CGRectMake
 
+/**
+ * SkiaLayer implementation for macOS.
+ * Supports only [GraphicsApi.METAL]
+ */
 actual open class SkiaLayer {
     fun isShowing(): Boolean {
         return true
     }
 
+    /**
+     * [GraphicsApi.METAL] is the only GraphicsApi supported for macOS.
+     * Setter throws an IllegalArgumentException if the value is not [GraphicsApi.METAL].
+     */
     actual var renderApi: GraphicsApi = GraphicsApi.METAL
+        set(value) {
+            if (value != GraphicsApi.METAL) {
+                throw IllegalArgumentException("$field is not supported in macOS")
+            }
+            field = value
+        }
+
+    /**
+     * The scale factor of [NSWindow]
+     * https://developer.apple.com/documentation/appkit/nswindow/1419459-backingscalefactor
+     */
     actual val contentScale: Float
         get() = if (this::nsView.isInitialized) nsView.window!!.backingScaleFactor.toFloat() else 1.0f
 
+    /**
+     * Fullscreen is not supported
+     */
     actual var fullscreen: Boolean
         get() = false
         set(value) {
             if (value) throw IllegalArgumentException("fullscreen unsupported")
         }
 
+    /**
+     * Transparency is not supported on macOS native.
+     */
     actual var transparency: Boolean
         get() = false
         set(value) {
             if (value) throw IllegalArgumentException("transparency unsupported")
         }
 
+    /**
+     * Underlying [NSView]
+     */
     lateinit var nsView: NSView
 
+    /**
+     * Implements rendering logic and events processing.
+     */
     actual var skikoView: SkikoView? = null
 
     internal var redrawer: Redrawer? = null
 
+    /**
+     * Created/updated by recording in [update].
+     * It's used as a source for drawing on canvas in [draw].
+     */
     private var picture: PictureHolder? = null
     private val pictureRecorder = PictureRecorder()
 
+    /**
+     * @param container - should be an instance of [NSWindow]
+     */
     actual fun attachTo(container: Any) {
         attachTo(container as NSWindow)
     }
+
+    /**
+     * Initializes the [nsView] then adds it to [window]. Initializes events listeners.
+     * Delegates events processing to [skikoView].
+     */
     fun attachTo(window: NSWindow) {
         val (width, height) = window.contentLayoutRect.useContents {
             this.size.width to this.size.height
@@ -205,10 +248,16 @@ actual open class SkiaLayer {
         redrawer = null
     }
 
+    /**
+     * Schedules a frame to an appropriate moment.
+     */
     actual fun needRedraw() {
         redrawer?.needRedraw()
     }
 
+    /**
+     * Updates the [picture] according to current [nanoTime]
+     */
     internal fun update(nanoTime: Long) {
         val width = nsView.frame.useContents { size.width }
         val height = nsView.frame.useContents { size.height }

skiko/src/macosMain/kotlin/org/jetbrains/skiko/context/MetalContextHandler.macos.kt

@@ -9,8 +9,11 @@ import org.jetbrains.skiko.RenderException
 import org.jetbrains.skiko.SkiaLayer
 import org.jetbrains.skiko.redrawer.MacOsMetalRedrawer
 
+/**
+ * Metal ContextHandler implementation for MacOs.
+ */
 internal class MacOsMetalContextHandler(layer: SkiaLayer) : ContextHandler(layer, layer::draw) {
-    val metalRedrawer: MacOsMetalRedrawer
+    private val metalRedrawer: MacOsMetalRedrawer
         get() = layer.redrawer!! as MacOsMetalRedrawer
 
     override fun initContext(): Boolean {

skiko/src/macosMain/kotlin/org/jetbrains/skiko/context/OpenGLContextHandler.macos.kt

@@ -2,12 +2,18 @@ package org.jetbrains.skiko.context
 
 import kotlinx.cinterop.*
 import org.jetbrains.skia.*
+import org.jetbrains.skiko.GraphicsApi
 import org.jetbrains.skiko.RenderException
 import org.jetbrains.skiko.SkiaLayer
 import platform.OpenGL.GL_DRAW_FRAMEBUFFER_BINDING
 import platform.OpenGL.glGetIntegerv
 import platform.OpenGLCommon.GLenum
 
+/**
+ * OpenGL context handler for MacOs (native).
+ * Not used anymore, unless corresponding [GraphicsApi] is hardcoded in [SkiaLayer].
+ * See [MacOsMetalContextHandler] instead.
+ */
 internal class MacOSOpenGLContextHandler(layer: SkiaLayer) : ContextHandler(layer, layer::draw) {
     override fun initContext(): Boolean {
         try {

skiko/src/macosMain/kotlin/org/jetbrains/skiko/redrawer/MetalRedrawer.macos.kt

@@ -27,6 +27,11 @@ import platform.QuartzCore.kCALayerWidthSizable
 import kotlin.system.getTimeNanos
 import platform.CoreGraphics.CGSizeMake
 
+/**
+ * Metal [Redrawer] implementation for MacOs.
+ *
+ * See [MacOsMetalContextHandler]
+ */
 internal class MacOsMetalRedrawer(
     private val skiaLayer: SkiaLayer
 ) : Redrawer {
@@ -49,8 +54,16 @@ internal class MacOsMetalRedrawer(
         }
     }
 
-    fun makeContext() = DirectContext.makeMetal(device.objcPtr(), queue.objcPtr())
+    /**
+     * Creates and returns an instances of [DirectContext]
+     */
+    fun makeContext(): DirectContext = DirectContext.makeMetal(device.objcPtr(), queue.objcPtr())
 
+    /**
+     * Creates and returns an instances of [BackendRenderTarget] ready for rendering.
+     *
+     * https://developer.apple.com/documentation/quartzcore/cametallayer/1478172-nextdrawable
+     */
     fun makeRenderTarget(width: Int, height: Int): BackendRenderTarget {
         currentDrawable = metalLayer.nextDrawable()!!
         return BackendRenderTarget.makeMetal(width, height, currentDrawable!!.texture.objcPtr())
@@ -63,6 +76,9 @@ internal class MacOsMetalRedrawer(
         }
     }
 
+    /**
+     * Synchronizes the [metalLayer] size with the size of underlying nsView
+     */
     override fun syncSize() {
         syncContentScale()
         val osFrame = skiaLayer.nsView.frame
@@ -86,11 +102,17 @@ internal class MacOsMetalRedrawer(
         CATransaction.flush()
     }
 
+    /**
+     * Schedules a frame [draw] to an appropriate moment.
+     */
     override fun needRedraw() {
         check(!isDisposed) { "MetalRedrawer is disposed" }
         frameDispatcher.scheduleFrame()
     }
 
+    /**
+     * Invokes [draw] right away.
+     */
     override fun redrawImmediately() {
         check(!isDisposed) { "MetalRedrawer is disposed" }
         draw()

skiko/src/macosMain/kotlin/org/jetbrains/skiko/redrawer/OpenGLRedrawer.macos.kt

@@ -17,6 +17,11 @@ import platform.QuartzCore.CAOpenGLLayer
 import platform.QuartzCore.*
 import kotlin.system.getTimeNanos
 
+/**
+ * OpenGL [Redrawer] implementation for MacOs.
+ *
+ * Not actually used. See [SkiaLayer.renderApi]
+ */
 internal class MacOsOpenGLRedrawer(
     private val skiaLayer: SkiaLayer
 ) : Redrawer {