Add more documentation

Author: Patrick Hoette

.idea/copyright/MIT_Move.xml

@@ -0,0 +1,162 @@
+# M2Utility Project Guidelines
+
+## Project Overview
+
+M2Utility is a utility library designed to be used across a wide variety of projects. It provides flexible, extensible utilities that support a broad range of use cases. The project is structured as a multi-module Kotlin library with cross-platform (KMP) support.
+
+## Code Style
+
+### Kotlin Style Guide
+
+We follow the [official Kotlin style guide](https://kotlinlang.org/docs/coding-conventions.html) with the following additional requirements:
+
+- Use 4 spaces for indentation
+- Maximum line length is 120 characters
+- Use trailing commas in multi-line lists/arrays/parameters
+- Prefer named parameters for improved readability for functions with multiple parameters, especially when parameters share the same type
+- Always prefer explicit null handling; avoid `!!` (not null asserts) unless absolutely unavoidable
+- Use `require`, `requireNotNull`, `check`, `checkNotNull`, and `error` functions to enforce invariants early, and document these checks in KDoc comments
+
+### Documentation
+
+#### KDoc Comments
+
+- All public APIs must have KDoc comments
+- Use proper markdown formatting in KDoc
+- Include code examples where appropriate using markdown code blocks
+- Document all parameters, return values, and exceptions
+
+#### KDoc Tags
+
+- `@param` - Document all parameters with their purpose and constraints
+- `@property` - Document properties in classes, especially in data classes
+- `@return` - Document return values (not needed for functions returning `Unit`)
+- `@throws` - Document exceptions that the function explicitly throws
+- `@constructor` - Document class constructors when they have specific behavior
+- `@receiver` - Document extension function receivers to explain context
+- `@sample` - Use to reference sample code when available
+- `@deprecated` - Not supported by KDoc, use the `@Deprecated` annotation instead
+
+#### Markdown Style
+
+- Markdown headers should have a blank line above and below them
+- For Markdown headers use proper Title Casing (APA style)
+- For strong emphasis (bold) use `__text__`
+- For weak emphasis (italic) use `*text*`
+- Lists, code blocks, and quotes should have a blank line above and below them (except when they are part of a list)
+- Images should have a proper alt text and where possible a light and dark version as supported by GitHub
+- The Markdown dialect for md files is the GitHub flavor and for KDoc its the base Markdown dialect as supported by KDoc
+- Code blocks should always have a language specified where possible
+- For code references in Markdown either use a code block, inline code formatting (backticks), or for KDoc a KDoc style reference (example: `uses [SomeClass] to do things`)
+
+#### Deprecation
+
+For deprecated elements:
+
+- Add `@Deprecated` annotation with appropriate deprecation level and message
+- Include `replaceWith` parameter when possible to guide users to the new API
+- Document the reason for deprecation and migration path in KDoc
+
+Example:
+
+```kotlin
+/**
+ * This method performs an operation that is now deprecated.
+ */
+@Deprecated(
+    message = "Use newMethod() instead which provides better performance",
+    replaceWith = ReplaceWith("newMethod()"),
+    level = DeprecationLevel.WARNING
+)
+fun oldMethod() {
+    // Implementation
+    newMethod() // Delegate to new method when possible
+}
+```
+
+### Changelog
+
+- Follow the [Keep a Changelog](https://keepachangelog.com/) format
+- Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security, or Dependencies
+- Version numbers are a single number incremented by 1 for each release
+- Older releases are not maintained for this internal project
+- For new releases the current date should be included in the header
+- Change entries should be prefix with the correct module like `- __test:__ Added some function`
+- For breaking changes a `(Breaking)` should be suffixed to the change module prefix like `- __test (Breaking): Changed parameters of some function`
+
+### Module Documentation
+
+- Each module should have a comprehensive README.md
+- README files should be properly formatted for Dokka to generate documentation HTML for GitHub Pages
+- Include module purpose, main components, usage examples, and integration instructions for larger systems/functionality only
+
+## Code Quality
+
+### Static Analysis
+
+All code must pass:
+
+- Android lint checks
+- Detekt analysis (configuration in detekt-config.yml)
+- SonarQube analysis
+
+### Testing Requirements
+
+- All new code should have appropriate unit tests
+- Follow Behavior-Driven Testing principles with Given-When-Then structure
+- Test coverage should be maintained or improved with new code
+- Testing shared code should be prioritized over platform-specific tests where possible
+- Where relevant use a @ParameterizedTest
+- Bug fixes should have tests for them where possible
+
+### Testing Stack
+
+- JUnit 5 for test framework
+- MockK for mocking
+- EasyRandom for test data generation
+- Turbine for testing Flow
+- Custom utilities from test and test-android modules
+
+## Design Principles
+
+- **Flexibility**: Code should be adaptable to different use cases
+- **Extensibility**: Design for extension through inheritance or composition
+- **Reusability**: Components should be reusable across different projects
+- **Maintainability**: Code should be easy to understand and maintain
+- **Performance**: Consider performance implications, especially for utility functions
+
+## API Design and Maintenance
+
+### Public API Guidelines
+
+- For any public-facing API (including internal expect/actual in KMP), changes should:
+    - Avoid breaking changes unless justified and properly documented
+    - Consider using deprecation cycles (WARNING → ERROR → removal over releases)
+- For expect/actual declarations make sure to document platform specific implementations clearly. Also avoid leaking platform-specific concepts into common code
+- When APIs are only available on some targets explicitly mention it in KDoc
+
+### Coroutines
+
+- Use structured concurrency. Avoid GlobalScope (as per coroutine best practices)
+- Document coroutine context switches or expectations clearly in the KDocs
+- Prefer suspend functions and flows over callbacks
+
+## Versioning and Maintenance
+
+- Version numbers are incremented by 1 for each release
+- Only the latest version is maintained
+- Breaking changes should be clearly documented in the changelog
+
+## Dependencies Management
+
+### Dependency Guidelines
+
+- New dependencies should only be added when needed and only exposed using API in very rare exceptions
+- Use Kotlin stdlib and kotlinx libraries over alternatives where feasible
+- Dependencies that impact public API require extra scrutiny
+
+### Gradle Version Catalogue
+
+- New dependencies should be added using the Gradle version catalogue system
+- Use the standard `gradle/libs.versions.toml` file for version declarations
+- Follow the established pattern for declaring library versions and dependencies

.idea/copyright/profiles_settings.xml

@@ -1,17 +1,18 @@
 [versions]
 accompanist = "0.32.0"
 activityCompose = "1.9.2"
-android-gradle = "8.5.2"
+android-gradle = "8.11.1"
 coil = "2.7.0"
 composeBom = "2024.09.01"
 composeCompiler = "1.5.8"
 coreKtx = "1.13.1"
 detekt = "1.23.5"
 flexmark = "0.64.8"
-immutableCollections = "0.3.7"
+immutableCollections = "0.4.0"
 jvm = "17"
 kodeview = "0.9.0"
-kotlin = "2.0.10"
+kotlin = "2.2.0"
+coreKtxVersion = "1.16.0"
 
 [libraries]
 accompanist-systemuicontroller = { module = "com.google.accompanist:accompanist-systemuicontroller", version.ref = "accompanist" }
@@ -33,6 +34,7 @@ flexmark-superscript = { module = "com.vladsch.flexmark:flexmark-ext-superscript
 flexmark-tables = { module = "com.vladsch.flexmark:flexmark-ext-tables", version.ref = "flexmark" }
 immutable-collections = { module = "org.jetbrains.kotlinx:kotlinx-collections-immutable", version.ref = "immutableCollections" }
 kodeview = { module = "dev.snipme:kodeview", version.ref = "kodeview" }
+androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtxVersion" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "android-gradle" }

.junie/guidelines.md

@@ -1,6 +1,24 @@
+#
+# Copyright © 2025 Framna
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the ?Software?), to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+# to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+# the Software.
+#
+# THE SOFTWARE IS PROVIDED ?AS IS?, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+# THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+# CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+
 #Sat Oct 01 16:01:34 CEST 2022
 distributionBase=GRADLE_USER_HOME
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
 distributionPath=wrapper/dists
 zipStorePath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME

gradle/libs.versions.toml

@@ -1,3 +1,21 @@
+/*
+ * Copyright © 2025 Framna
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the “Software”), to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+ * the Software.
+ *
+ * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
 @file:Suppress("UnstableApiUsage")
 
 plugins {
@@ -48,6 +66,7 @@ android {
             "-P",
             "plugin:androidx.compose.compiler.plugins.kotlin:metricsDestination=${rootDir.absolutePath}/compose_metrics"
         )
+        jvmTarget = "17"
     }
 
     lint {
@@ -59,37 +78,11 @@ android {
     }
 }
 
-afterEvaluate {
-    publishing {
-        publications {
-            create<MavenPublication>("mavenRelease") {
-                groupId = BuildConstants.Namespace
-                version = BuildConstants.VersionName
-                from(components.getByName("release"))
-                pom {
-                    name.set("MarkyMark-Android")
-                    description.set("Library for converting Markdown to Android Jetpack Compose elements")
-                    url.set("https://git.m2mobi.com/projects/ML/repos/m2utility/browse")
-                    licenses {
-                        license {
-                            name.set("The MIT License (MIT)")
-                            url.set("https://raw.githubusercontent.com/Move-Agency/MarkyMark-Android/v3/develop/LICENSE")
-                        }
-                    }
-                    organization {
-                        name.set("Move Agency")
-                        url.set("https://www.moveagency.com/")
-                    }
-                }
-            }
-        }
-    }
-}
-
 dependencies {
     implementation(platform(libs.compose.bom))
     implementation(libs.compose.ui)
     implementation(libs.compose.ui.tooling.preview)
+    implementation(libs.androidx.core.ktx)
     debugImplementation(libs.compose.ui.tooling)
     implementation(libs.compose.material3)
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Move
+ * Copyright © 2025 Framna
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
  * documentation files (the “Software”), to deal in the Software without restriction, including without limitation
@@ -24,16 +24,35 @@ import com.moveagency.markymark.theme.LocalMarkyMarkTheme
 import com.moveagency.markymark.theme.MarkyMarkTheme
 
 /**
- * Helper object for accessing [LocalMarkyMarkOptions] & [LocalMarkyMarkTheme].
+ * Central access point for MarkyMark configuration and theming.
+ *
+ * This object provides access to the current [MarkyMarkOptions] and [MarkyMarkTheme]
+ * through composition locals, making them available throughout the composition hierarchy.
+ * It serves as a convenient way to access markdown rendering configuration and styling
+ * from any composable function.
  */
 object MarkyMark {
 
+    /**
+     * The current markdown rendering options.
+     *
+     * This property provides access to the current [MarkyMarkOptions] from the [LocalMarkyMarkOptions]
+     * composition local. It includes configuration for the FlexMark parser, custom composers,
+     * and annotators used for rendering markdown content.
+     */
     @Suppress("ObjectPropertyNaming")
     val options: MarkyMarkOptions
         @Composable
         @ReadOnlyComposable
         get() = LocalMarkyMarkOptions.current
 
+    /**
+     * The current markdown styling theme.
+     *
+     * This property provides access to the current [MarkyMarkTheme] from the [LocalMarkyMarkTheme]
+     * composition local. It includes styling for all markdown elements, including root-level
+     * styling, element-specific styles, and color schemes.
+     */
     @Suppress("ObjectPropertyNaming")
     val theme: MarkyMarkTheme
         @Composable