docs: add proper documentation

Author: ObserverOfTime

.github/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing
+
+## Commits
+
+Commits must follow the [Conventional Commits] specification.
+If you're developing on IntelliJ IDEA or Android Studio,
+you can use the [Conventional Commit plugin].
+
+[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/
+[Conventional Commit plugin]: https://plugins.jetbrains.com/plugin/13389-conventional-commit
+
+## Prerequisites
+
+- JDK 17+
+- Android SDK & NDK
+- CMake
+- C compiler
+
+## Building
+
+### Clone the repository
+
+```shell
+git clone https://github.com/tree-sitter/kotlin-tree-sitter
+cd kotlin-tree-sitter
+```
+
+### Build the JNI libraries
+
+*This step is only necessary for JVM or Android development.*
+
+Generate the grammar files:
+
+```shell
+./gradlew generateGrammarFiles
+```
+
+Set the `CMAKE_INSTALL_LIBDIR` environment variable.
+The value depends on your system:
+
+- `lib/linux/x64`
+- `lib/linux/aarch64`
+- `lib/macos/x64`
+- `lib/macos/aarch64`
+- `lib/windows/x64`
+
+Build the libraries (change `.sh` to `.ps1` on Windows):
+
+```shell
+./.github/scripts/build-jni.sh
+```
+
+### Run the tests
+
+#### JVM
+
+```shell
+./gradlew :ktreesitter:jvmTest
+```
+
+#### Android
+
+*Requires a connected device.*
+
+```shell
+./gradlew :ktreesitter:connectedDebugAndroidTest
+```
+
+#### Native
+
+Linux:
+
+```shell
+./gradlew :ktreesitter:linuxX64Test
+```
+
+macOS:
+
+```shell
+# x64
+./gradlew :ktreesitter:macosX64Test
+# arm64
+./gradlew :ktreesitter:macosArm64Test
+```
+
+Windows:
+
+```shell
+./gradlew :ktreesitter:mingwX64Test
+```
+
+## Linting
+
+Code linting is performed using [Ktlint] and [detekt].
+Configuration for IntelliJ IDEA and Android Studio is included
+(requires the [Ktlint][Ktlint plugin] and [detekt][detekt plugin] plugins).
+
+[Ktlint]: https://pinterest.github.io/ktlint/latest/
+[detekt]: https://detekt.dev/
+[Ktlint plugin]: https://plugins.jetbrains.com/plugin/15057-ktlint
+[detekt plugin]: https://plugins.jetbrains.com/plugin/10761-detekt

README.md

@@ -1,28 +1,26 @@
-# KTreeSitter
-
-Kotlin bindings to the Tree-sitter parsing library
-
-## TODO
-
-- [x] CI
-- [ ] Implementation
-  - [x] Native
-  - [x] JVM
-  - [x] Android
-  - [ ] WASI?
-- [x] Documentation
-- [ ] Bundled languages
-  - [ ] Kotlin
-  - [x] Java
-  - [ ] Groovy
-  - [ ] Properties
-  - [ ] XML
-  - [ ] C
-  - [ ] C++
-  - [ ] Objective-C
-  - [ ] Swift
-  - [ ] Markdown
-  - [ ] CMake
-- [x] Gradle plugin
-- [ ] Package
-- [ ] DSL?
+# Kotlin Tree-sitter
+
+[![CI][ci]](https://github.com/tree-sitter/kotlin-tree-sitter/actions/workflows/ci.yml)
+[![central][central]](https://central.sonatype.com/artifact/io.github.tree-sitter/ktreesitter)
+[![docs][docs]](https://tree-sitter.github.io/kotlin-tree-sitter/)
+
+Kotlin bindings to the [tree-sitter] parsing library.
+
+## Modules
+
+### ktreesitter
+
+The KTreeSitter library module.
+
+### ktreesitter-plugin
+
+The plugin responsible for generating source files for languages.
+
+### languages
+
+Some bundled languages that are relevant to Kotlin development.
+
+[tree-sitter]: https://tree-sitter.github.io/tree-sitter/
+[ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/kotlin-tree-sitter/ci.yml?logo=github&label=CI
+[central]: https://img.shields.io/maven-central/v/io.github.tree-sitter/ktreesitter?logo=sonatype&label=Maven%20Central
+[docs]: https://img.shields.io/github/deployments/tree-sitter/kotlin-tree-sitter/github-pages?logo=kotlin&label=Docs

ktreesitter-plugin/README.md

@@ -0,0 +1,44 @@
+# KTreeSitter plugin
+
+A plugin that generates code for KTreeSitter grammar packages.
+
+## Installation
+
+```groovy
+buildscript {
+  repositories {
+    gradlePluginPortal()
+  }
+}
+
+plugins {
+  id("io.github.tree-sitter.ktreesitter-plugin")
+}
+```
+
+## Configuration
+
+```groovy
+grammar {
+  /* Default options */
+  // The base directory of the grammar
+  baseDir = projectDir.parentFile.parentFile
+  // The name of the C interop def file
+  interopName = "grammar"
+  // The name of the JNI library
+  libraryName = "ktreesitter-$grammarName"
+
+  /* Required options */
+  // The name of the grammar
+  grammarName = "java"
+  // The name of the class
+  className = "TreeSitterJava"
+  // The name of the package
+  packageName = "io.github.treesitter.ktreesitter.java"
+  // The source files of the grammar
+  files = arrayOf(
+    baseDir.get().resolve("src/parser.c"),
+    // baseDir.get().resolve("src/scanner.c")
+  )
+}
+```

ktreesitter-plugin/build.gradle.kts

@@ -23,7 +23,7 @@ java {
 @Suppress("UnstableApiUsage")
 gradlePlugin {
     vcsUrl = "https://github.com/tree-sitter/kotlin-tree-sitter"
-    website = "https://github.com/tree-sitter/kotlin-tree-sitter/tree/master/plugin"
+    website = "https://github.com/tree-sitter/kotlin-tree-sitter/tree/master/ktreesitter-plugin"
     plugins.create("ktreesitter") {
         id = "$group.${project.name}"
         displayName = "KTreeSitter grammar plugin"

ktreesitter/README.md

@@ -0,0 +1,39 @@
+# KTreeSitter
+
+Kotlin bindings to the [tree-sitter] parsing library.
+
+## Supported platforms
+
+- [x] JVM
+- [x] Android
+- [x] Native
+- [ ] WASI
+
+*JS and WASM JS will not be supported.*
+
+## Installation
+
+```groovy
+dependencies {
+    implementation("io.github.tree-sitter:ktreesitter") version $ktreesitterVersion
+}
+
+repositories {
+    mavenCentral()
+}
+```
+
+## Basic usage
+
+```kotlin
+import io.github.treesitter.ktreesitter.*
+import io.github.treesitter.ktreesitter.java.TreeSitterJava
+
+val language = Language(TreeSitterJava.language())
+val parser = Parser(language)
+val tree = parser.parse("class Foo {}")
+
+assert(tree.rootNode.type == "program")
+```
+
+[tree-sitter]: https://tree-sitter.github.io/tree-sitter/

ktreesitter/build.gradle.kts

@@ -209,11 +209,10 @@ signing {
 
 tasks.dokkaHtml {
     val tmpDir = layout.buildDirectory.get().dir("tmp")
-    val readme = rootDir.resolve("README.md")
     val ref = System.getenv("GITHUB_SHA")?.subSequence(0, 7) ?: "master"
     val url = "https://github.com/tree-sitter/kotlin-tree-sitter/blob/$ref/ktreesitter"
 
-    inputs.file(readme)
+    inputs.file(file("README.md"))
 
     moduleName.set("KTreeSitter")
 
@@ -226,8 +225,7 @@ tasks.dokkaHtml {
     dokkaSourceSets.configureEach {
         jdkVersion.set(17)
         noStdlibLink.set(true)
-        // TODO: uncomment when ready
-        // includes.from(tmpDir.file("README.md"))
+        includes.from(tmpDir.file("README.md"))
         externalDocumentationLink("https://kotlinlang.org/api/core/")
         sourceLink {
             localDirectory.set(projectDir)
@@ -237,9 +235,13 @@ tasks.dokkaHtml {
 
     doFirst {
         copy {
-            from(readme)
+            from(file("README.md"))
             into(tmpDir)
-            filter { it.replaceFirst("# KTreeSitter", "# Module KTreeSitter") }
+            filter { file ->
+                file.replaceFirst("# KTreeSitter", "# Module KTreeSitter")
+                    .replaceFirst("\$ktreesitterVersion", "\"$version\"")
+                    .replace("[x]", "☑").replace("[ ]", "☐")
+            }
         }
     }
 

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/Language.kt

@@ -103,7 +103,10 @@ actual class Language @Throws(IllegalArgumentException::class) actual constructo
     /**
      * Create a new [Query] from a string containing one or more S-expression
      * [patterns](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax).
+     *
+     * @throws [QueryError] If any error occurred while creating the query.
      */
+    @Throws(QueryError::class)
     actual fun query(source: String) = Query(this, source)
 
     actual override fun equals(other: Any?) =

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/Parser.kt

@@ -34,7 +34,7 @@ actual class Parser actual constructor() : AutoCloseable {
      * The ranges of text that the parser will include when parsing.
      *
      * By default, the parser will always include entire documents.
-     * Setting this property allows you to parse only a *portion* of a
+     * Setting this property allows you to parse only a _portion_ of a
      * document but still return a syntax tree whose ranges match up with
      * the document as a whole. You can also pass multiple disjoint ranges.
      *

ktreesitter/src/commonMain/kotlin/io/github/treesitter/ktreesitter/Language.kt

@@ -69,7 +69,10 @@ expect class Language @Throws(IllegalArgumentException::class) constructor(langu
     /**
      * Create a new [Query] from a string containing one or more S-expression
      * [patterns](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax).
+     *
+     * @throws [QueryError] If any error occurred while creating the query.
      */
+    @Throws(QueryError::class)
     fun query(source: String): Query
 
     override fun equals(other: Any?): Boolean

ktreesitter/src/commonMain/kotlin/io/github/treesitter/ktreesitter/Parser.kt

@@ -33,7 +33,7 @@ expect class Parser() {
      * The ranges of text that the parser will include when parsing.
      *
      * By default, the parser will always include entire documents.
-     * Setting this property allows you to parse only a *portion* of a
+     * Setting this property allows you to parse only a _portion_ of a
      * document but still return a syntax tree whose ranges match up with
      * the document as a whole. You can also pass multiple disjoint ranges.
      *