add documentation to all new functions

common/src/commonMain/kotlin/pro/respawn/kmmutils/common/CommonExt.kt

@@ -123,12 +123,33 @@ public fun Throwable?.rethrowErrors(): Exception? = this?.let { it as? Exception
 @JvmName("rethrowErrorsNotNull")
 public fun Throwable.rethrowErrors(): Exception = this as? Exception? ?: throw this
 
+/**
+ * Encode this string to Base64
+ */
 public fun String.toBase64(): String = encodeToByteArray().toBase64()
 
+/**
+ * Encode this byte array to base 64
+ */
 @OptIn(ExperimentalEncodingApi::class)
 public fun ByteArray.toBase64(): String = Base64.Default.encode(this)
 
+/**
+ * Add quotes to this string, if not present. Will do nothing to `null`s.
+ *
+ * Will turn :
+ * * `foo` -> `"foo"`,
+ * * `"foo"` -> `"foo"` (no change)
+ * * `null` -> `null` (no change)
+ */
 @get:JvmName("quotedOrNull")
 public inline val String?.quoted: String? get() = this?.quoted
 
-public inline val String.quoted: String get() = "\"${removeSuffix("")}\""
+/**
+ * Add quotes to this string, if not present.
+ *
+ * Will turn :
+ * * `foo` -> `"foo"`,
+ * * `"foo"` -> `"foo"` (no change)
+ */
+public inline val String.quoted: String get() = """"${removeSurrounding("\"")}""""

compose/build.gradle.kts

@@ -49,14 +49,14 @@ kotlin {
             implementation(compose.foundation)
             implementation(compose.animationGraphics)
             implementation(compose.animation)
-            implementation(projects.system)
         }
         jvmMain.dependencies {
             implementation(compose.desktop.common)
         }
         androidMain.dependencies {
             api(libs.androidx.lifecycle.viewmodel)
             api(libs.androidx.activity.compose)
+            implementation(projects.system)
         }
     }
 }

compose/src/androidMain/kotlin/pro/respawn/kmmutils/compose/SdkIntExt.android.kt

@@ -3,11 +3,21 @@ package pro.respawn.kmmutils.compose
 import android.os.Build
 import androidx.annotation.ChecksSdkIntAtLeast
 
+/**
+ * @returns whether Blur composition is currently supported.
+ * Currently returns `false` on all platforms except android as this is not yet implemented in Compose.
+ */
 @get:ChecksSdkIntAtLeast(api = Build.VERSION_CODES.S)
-public actual val supportsBlur: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+public val supportsBlur: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
 
+/**
+ * @return whether dynamic colors are supported. Only supported on Android since S, all other platforms return false
+ */
 @get:ChecksSdkIntAtLeast(api = Build.VERSION_CODES.S)
-public actual val supportsDynamicColors: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+public val supportsDynamicColors: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
 
+/**
+ * @return whether dynamic colors are supported. Only supported on Android since S, all other platforms return false
+ */
 @get:ChecksSdkIntAtLeast(api = Build.VERSION_CODES.TIRAMISU)
-public actual val supportsShaders: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU
+public val supportsShaders: Boolean get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU

compose/src/androidMain/kotlin/pro/respawn/kmmutils/compose/Service.kt

@@ -15,6 +15,14 @@ import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.LocalContext
 
+/**
+ * Remembers a reference to a [Service] [BoundService]'s [Binder] [BoundServiceBinder] in composition.
+ * The function will bind to a service while it is in the composition and unbind when it has left the composition.
+ * The function will maintain a [ServiceConnection] and return a [State] with a nullable value of service.
+ *
+ * Binding to the service takes some time and connection breakages can occur,
+ * so the return state value may be null at times.
+ */
 @Composable
 @Suppress("ComposableParametersOrdering")
 public inline fun <reified BoundService : Service, reified BoundServiceBinder : Binder> rememberBoundLocalService(

compose/src/androidMain/kotlin/pro/respawn/kmmutils/compose/windowsize/WindowSizeExt.android.kt

@@ -0,0 +1,22 @@
+package pro.respawn.kmmutils.compose.windowsize
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.ReadOnlyComposable
+import androidx.compose.ui.ExperimentalComposeUiApi
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.IntSize
+import androidx.compose.ui.unit.dp
+
+/**
+ * Get the window size of the current window in pixels.
+ * This matches closely width screen size on mobile devices most of the time, but windows can be resized by the user.
+ */
+@ExperimentalComposeUiApi
+public actual val windowSizePx: IntSize
+    @ReadOnlyComposable
+    @Composable get() = with(LocalDensity.current) {
+        with(LocalConfiguration.current) {
+            IntSize(screenWidthDp.dp.roundToPx(), screenHeightDp.dp.roundToPx())
+        }
+    }

compose/src/commonMain/kotlin/pro/respawn/kmmutils/compose/Annotations.kt

@@ -13,51 +13,121 @@ import androidx.compose.ui.text.style.TextDecoration
 import androidx.compose.ui.text.withStyle
 import androidx.compose.ui.unit.TextUnit
 
-public fun String.span(spanStyle: SpanStyle): AnnotatedString = buildAnnotatedString {
+/**
+ * Annotates this string with the [spanStyle] provided. The whole string is annotated.
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.annotate(spanStyle: SpanStyle): AnnotatedString = buildAnnotatedString {
     withStyle(spanStyle) {
-        append(this@span)
+        append(this@annotate)
     }
 }
 
-public fun String.bold(): AnnotatedString = span(SpanStyle(fontWeight = FontWeight.Bold))
+/**
+ * Produces an annotated string identical to the original string
+ * For those times when an api requires AnnotatedString but you don't want to build one
+ */
+public fun String.annotate(): AnnotatedString = AnnotatedString(this)
 
-public fun String.italic(): AnnotatedString = span(SpanStyle(fontStyle = FontStyle.Italic))
+/**
+ * Annotates this string using the [builder] provided. The string is the argument of the lambda.
+ *
+ * @return the [AnnotatedString] created
+ */
+public inline fun String.annotate(
+    builder: AnnotatedString.Builder.(String) -> Unit
+): AnnotatedString = buildAnnotatedString { builder(this@annotate) }
 
-public fun String.strike(): AnnotatedString = span(SpanStyle(textDecoration = TextDecoration.LineThrough))
+/**
+ * Applies [FontWeight.Bold] to `this` string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.bold(): AnnotatedString = weight(FontWeight.Bold)
 
-public fun String.underline(): AnnotatedString = span(SpanStyle(textDecoration = TextDecoration.Underline))
+/**
+ * Applies [FontStyle.Italic] to `this` string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.italic(): AnnotatedString = style(FontStyle.Italic)
+
+/**
+ * Strikes through this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.strike(): AnnotatedString = annotate(SpanStyle(textDecoration = TextDecoration.LineThrough))
+
+/**
+ * Adds an underline to this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.underline(): AnnotatedString = annotate(SpanStyle(textDecoration = TextDecoration.Underline))
 
+/**
+ * Adds text [decorations] provided to this string
+ *
+ * @return the [AnnotatedString] created
+ */
 public fun String.decorate(
     vararg decorations: TextDecoration
-): AnnotatedString = span(SpanStyle(textDecoration = TextDecoration.combine(decorations.asList())))
+): AnnotatedString = annotate(SpanStyle(textDecoration = TextDecoration.combine(decorations.asList())))
 
-public fun String.size(size: TextUnit): AnnotatedString = span(SpanStyle(fontSize = size))
+/**
+ * Applies absolute [size] to the text
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.size(size: TextUnit): AnnotatedString = annotate(SpanStyle(fontSize = size))
 
-public fun String.background(color: Color): AnnotatedString = span(SpanStyle(background = color))
+/**
+ * Sets the background [color] to this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.background(color: Color): AnnotatedString = annotate(SpanStyle(background = color))
 
-public fun String.color(color: Color): AnnotatedString = span(SpanStyle(color = color))
+/**
+ * Sets the foreground [color] of this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.color(color: Color): AnnotatedString = annotate(SpanStyle(color = color))
 
-public fun String.weight(weight: FontWeight): AnnotatedString = span(SpanStyle(fontWeight = weight))
+/**
+ * Sets the font [weight] for this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.weight(weight: FontWeight): AnnotatedString = annotate(SpanStyle(fontWeight = weight))
 
-public fun String.style(style: FontStyle): AnnotatedString = span(SpanStyle(fontStyle = style))
+/**
+ * Applies a [style] [FontStyle] to this string
+ *
+ * @return the [AnnotatedString] created
+ */
+public fun String.style(style: FontStyle): AnnotatedString = annotate(SpanStyle(fontStyle = style))
 
+/**
+ * Adds a shadow to `this` string. The shadow has a [color], an [offset] and a [blurRadius]
+ *
+ * @return the [AnnotatedString] created
+ */
 public fun String.shadow(
     color: Color,
     offset: Offset = Offset.Zero,
     blurRadius: Float = 0.0f
-): AnnotatedString = span(SpanStyle(shadow = Shadow(color, offset, blurRadius)))
-
-public fun String.fontFamily(fontFamily: FontFamily): AnnotatedString = span(SpanStyle(fontFamily = fontFamily))
+): AnnotatedString = annotate(SpanStyle(shadow = Shadow(color, offset, blurRadius)))
 
 /**
- * Produces an annotated string identical to the original string
- * For those times when an api requires AnnotatedString but you don't want to build one
+ * Changes the [fontFamily] of this string
+ *
+ * @return the [AnnotatedString] created
  */
-public fun String.annotate(): AnnotatedString = AnnotatedString(this)
-
-@Suppress("ComposableEventParameterNaming")
-public inline fun String.annotate(builder: AnnotatedString.Builder.(String) -> Unit): AnnotatedString =
-    buildAnnotatedString { builder(this@annotate) }
+public fun String.font(fontFamily: FontFamily): AnnotatedString = annotate(SpanStyle(fontFamily = fontFamily))
 
 // TODO: Waiting for compose update
 

compose/src/commonMain/kotlin/pro/respawn/kmmutils/compose/GraphicsLayerExt.kt

@@ -45,6 +45,9 @@ public fun FractionalOffset.asAbsolute(size: Size): Offset = Offset(x * size.wid
  */
 public fun Offset.asFractional(size: Size): FractionalOffset = Offset(x / size.width, y / size.height)
 
+/**
+ * Applies an [offset] to this [GraphicsLayerScope]
+ */
 public fun GraphicsLayerScope.offset(offset: Offset) {
     translationX = offset.x
     translationY = offset.y

compose/src/commonMain/kotlin/pro/respawn/kmmutils/compose/Haptics.kt

@@ -5,6 +5,20 @@ package pro.respawn.kmmutils.compose
 import androidx.compose.ui.hapticfeedback.HapticFeedback
 import androidx.compose.ui.hapticfeedback.HapticFeedbackType
 
+/**
+ * Plays a medium haptic feedback, similar to force-touch or long-tap effect.
+ *
+ * The effect can vary between platforms or be unavailable (e.g. desktop, browser).
+ *
+ * @see HapticFeedbackType.LongPress
+ */
 public fun HapticFeedback.medium(): Unit = performHapticFeedback(HapticFeedbackType.LongPress)
 
+/**
+ * Plays a short haptic feedback, similar to a software keyboard typing vibration.
+ *
+ * The effect can vary between platforms or be unavailable (e.g. desktop, browser).
+ *
+ * @see HapticFeedbackType.TextHandleMove
+ */
 public fun HapticFeedback.short(): Unit = performHapticFeedback(HapticFeedbackType.TextHandleMove)