Provide friendly description SKaiNET API for devs and AI

[michalharakal]

• Dokka API reference (HTML/Javadoc/Markdown)

  Generate docs from KDoc across common + platform source sets, including expect/actual.
  Gradle:

  plugins { id("org.jetbrains.dokka") version "1.9.20" }
  tasks.dokkaHtml { /* configure as needed */ }
  // optionally publish as javadoc.jar:
  tasks.register<Jar>("javadocJar") {
      archiveClassifier.set("javadoc")
      from(tasks.dokkaHtml)
  }

• Public API dump (human-readable spec) + binary compatibility checks
  Use the Kotlin binary-compatibility-validator to generate/textualize your public API and fail CI on breaking changes. The api/*.api files double as an API spec users can read in the repo.

  plugins { id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.16.3" }
  apiValidation {
      // e.g., ignoredProjects += "samples"
  }
  // ./gradlew apiDump  -> generates api/*.api

• “Explicit API” mode for clean, deliberate surfaces
  Forces visibility + return types + KDoc on public members; results in higher-quality docs/specs.

  kotlin { explicitApi() }

• Sources artifact
  Ship a -sources.jar so IDEs show signatures and KDoc instead of decompiled stubs.

  java { withSourcesJar() } // plus withJavadocJar() if you want a javadoc classifier

JVM target

• Publish normal Java/Kotlin stubs & sources
  Standard Maven/Gradle consumers get types/kdocs via sources; no decompile needed.

• Preserve parameter names for better IDE/reflection

  tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
      kotlinOptions.freeCompilerArgs += listOf("-Xjsr305=strict")
      // For Java consumers:
      (this as? org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile)?.apply {
          kotlinOptions.javaParameters = true // keeps parameter names in bytecode
      }
  }

• Optional Java stubs / Javadoc format
  If you have many Java users, publish a Dokka Javadoc variant as javadoc.jar.

Android target

• AAR with sources + Dokka site
  Android Studio will show API from sources; Dokka site is your canonical ref.
• Metalava (optional, Android ecosystem)
  If you want the Android-style .api text spec (like AndroidX), run Metalava to generate + check API signatures. (This is in addition to—or instead of—binary-compatibility-validator.)

iOS / Kotlin/Native targets

• XCFramework with Swift/Obj-C headers
  The produced framework/xcframework includes generated Swift/Obj-C interfaces—this is the API surface for Apple platforms. Ship it via Swift Package Manager or a binary release.

  • Provide a minimal SPM package (or .xcframework + Package.swift) so Xcode users see the API in Quick Help/Autocomplete.
  • Include a small “Swift interop guide” in your docs (naming, nullability, suspend → async, collections mapping).

• Reference docs for Apple devs
  Consider generating an Apple-style docset (or just host Dokka with a Swift usage section).

JS target

• TypeScript declaration files (.d.ts)
  Generate TS typings from Kotlin/JS IR so JS/TS consumers get strong typing in editors—no decompile, no guessing.

  kotlin {
      js(IR) {
          binaries.executable()
          // or for libraries:
          binaries.library()
          generateTypeScriptDefinitions()
      }
  }

  Publish to npm with the .d.ts alongside the bundle.

Distribution “glue” that helps everyone

• Maven/Gradle module metadata
  Publish with the standard maven-publish setup so consumers resolve the right variant automatically.
• Changelog + SemVer + “Breaking changes” section
  Pair your API dump with human notes.
• Samples & Quickstarts
  Short, runnable examples per platform are often more useful than raw signatures.

What to ship, concretely

• A Dokka site (HTML) and a javadoc.jar artifact.
• A -sources.jar for every published target (JVM/AAR; for iOS, ship source in repo even if consumers use a binary XCFramework).
• A public API text spec (api/*.api) generated by binary-compatibility-validator (or Metalava on Android).
• For JS, a .d.ts file next to the package.
• For iOS, a binary XCFramework via SPM (with generated Swift interface), plus a short interop guide.

This combo gives consumers editor-native API visibility on every platform—no bytecode decompiling required. If you want, tell me your targets (JVM/Android/iOS/JS) and I’ll drop in ready-to-paste Gradle snippets for your exact setup.