Kotools Samples

Kotools Samples is a Gradle plugin designed to help Kotlin library authors integrate read-only samples into their documentation. It addresses a limitation in Dokka, which does not allow making code samples non-editable or non-executable.

⭐️ Key Features

• Readonly inlined code samples: Displays your examples inlined in the documentation, ensuring they are non-editable and non-executable, preventing unwanted modification or execution.
• Sample visibility in IDE: Unlike many libraries (such as Jetpack Compose), Kotools Samples makes your examples visible within the IDE (e.g., IntelliJ IDEA, Android Studio), enhancing accessibility and usability during development.
• Always correct samples: Ensures your examples are always up-to-date by compiling them alongside your main and test sources. Any breaking changes in your codebase will trigger compilation errors, prompting you to update the examples.
• Kotlin/JVM support: Fully supports the Kotlin/JVM platform, with Kotlin Multiplatform support in future releases.
• Seamless integration: Works effortlessly with Kotlin and Dokka, smoothly integrating into your Gradle build process.

🛠️ Installation

For adding Kotools Samples to your Kotlin/JVM project, it is recommended to use the Gradle plugins DSL in Kotlin. Just replace the $version variable by the latest version or by another one available in the changelog.

plugins {
    id("org.kotools.samples") version "$version"
}

See this plugin on the Gradle Plugin Portal for more installation options.

The org.kotools.samples.jvm plugin is deprecated (see #42).

🧑‍💻 Usage example

Kotools Samples ensures that your code samples are integrated into your documentation without affecting your main sources. For doing so, it creates a source set named sample dedicated for code samples.

Here's a Kotlin sample:

// File location: src/sample/kotlin/IntSample.kt

import kotlin.test.Test

class IntSample {
    @Test
    fun addition() {
        val x = 1
        val y = 2
        check(x + y == 3)
    }
}

Reference this sample in your Dokka documentation:

// File location: src/main/kotlin/Int.kt

/**
 * Performs an addition with [x] and [y] integers (`x + y`).
 *
 * SAMPLE: [IntSample.addition]
 */
public fun addition(x: Int, y: Int): Int = x + y

Here's the documentation generated by Dokka with Kotools Samples:

✅ Supported constructs

Kotools Samples offers powerful features for writing expressive samples and integrating them into the documentation.

🧪 Sample sources

This Gradle plugin is able to extract the body of member functions, which can be an expression body, even from multiple classes located in the same file. In case of empty body, it extracts a placeholder indicating that the sample is not yet implemented.

Top-level functions being incompatible with the @Test annotation from Kotlin, they are not supported. This is for ensuring that all samples are testable.

package samples

import kotlin.test.Test

class FirstSample {
    @Test
    fun body() {
        val x = 1
        val y = 2
        check(x + y == 3)
    }

    @Test
    fun expressionBody(): Unit = check(1 + 2 == 3)
}

class SecondSample { // Multiple classes in single file is supported.
    @Test
    fun empty() {} // Placeholder: TODO("Sample is not yet implemented.")
}

🎯 Main sources

For integrating samples into the documentation, this plugin supports KDoc comments with one or multiple lines, containing one or more sample references.

/** SAMPLE: [samples.FirstSample.body] */
fun singleLineKDoc() = Unit

/**
 * SAMPLE: [samples.FirstSample.body]
 */
fun multiLineKDoc() = Unit

/**
 * SAMPLE: [samples.FirstSample.body]
 * SAMPLE: [samples.FirstSample.expressionBody]
 */
fun multipleSamples() = Unit

📝 Documentation

Here's additional documentation for learning more about this project:

• Dependency compatibility
• Security Policy

🤝 Community

Join our thriving community! Connect, share insights, and collaborate with fellow developers to make Kotools Samples even more powerful.

• #kotools on Kotlin Slack

📣 Show Your Support

If you find this project valuable, show your support by giving us a ⭐️ on GitHub. Your feedback and engagement mean the world to us!

🚧 Contributing

Contributions are welcome! Feel free to submit bug reports, feature requests, or pull requests to improve the plugin.

🙏 Acknowledgements

Thanks to Loïc Lamarque for creating and sharing this project with the open source community.

Thanks to all the people that ever contributed through code or other means such as bug reports, feature suggestions and so on.

📄 License

This project is licensed under the MIT License.