{"id":18141410,"url":"https://github.com/kotools/samples","last_synced_at":"2026-04-02T19:00:20.472Z","repository":{"id":257270325,"uuid":"856532435","full_name":"kotools/samples","owner":"kotools","description":"Gradle plugin that inlines read-only Kotlin and Java code samples into Dokka documentation, ensuring they are always correct and visible not only online but also in IDEs.","archived":false,"fork":false,"pushed_at":"2026-03-28T00:28:41.000Z","size":2060,"stargazers_count":29,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T00:29:20.054Z","etag":null,"topics":["dokka","gradle","java","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kotools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-12T18:27:35.000Z","updated_at":"2026-03-28T00:28:44.000Z","dependencies_parsed_at":"2024-09-15T17:03:34.929Z","dependency_job_id":"800ac7da-309a-471e-95cc-2a500e2dad14","html_url":"https://github.com/kotools/samples","commit_stats":null,"previous_names":["kotools/samples"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/kotools/samples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotools%2Fsamples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotools%2Fsamples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotools%2Fsamples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotools%2Fsamples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kotools","download_url":"https://codeload.github.com/kotools/samples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotools%2Fsamples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dokka","gradle","java","kotlin"],"created_at":"2024-11-01T17:06:49.365Z","updated_at":"2026-04-02T19:00:20.205Z","avatar_url":"https://github.com/kotools.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kotools Samples\n\n[![Latest][kotools-samples-badge]][kotools-samples-releases]\n[![Gradle][gradle-badge]][gradle]\n[![Kotlin][kotlin-badge]][kotlin]\n[![Java][java-badge]][java]\n[![Dokka][dokka-badge]][dokka]\n\n**Kotools Samples** is a [Gradle] plugin designed to help [Kotlin] library\nauthors integrate **read-only samples** into their documentation. It addresses a\nlimitation in [Dokka], which does not allow making code samples **non-editable**\nor **non-executable**.\n\n## ⭐️ Key Features\n\n- **Readonly inlined code samples:** Displays your examples inlined in the\n  documentation, ensuring they are non-editable and non-executable, preventing\n  unwanted modification or execution.\n- **Sample visibility in IDE:** Unlike many libraries (such as Jetpack Compose),\n  Kotools Samples makes your examples visible within the IDE (e.g.,\n  IntelliJ IDEA, Android Studio), enhancing accessibility and usability during\n  development.\n- **Always correct samples:** Ensures your examples are always up-to-date by\n  compiling them alongside your main and test sources. Any breaking changes in\n  your codebase will trigger compilation errors, prompting you to update the\n  examples.\n- **Kotlin/JVM support:** Fully supports the Kotlin/JVM platform, with [Kotlin]\n  Multiplatform support in future releases.\n- **Seamless integration:** Works effortlessly with [Kotlin] and [Dokka],\n  smoothly integrating into your Gradle build process.\n\n## 🛠️ Installation\n\nFor adding Kotools Samples to your Kotlin/JVM project, it is recommended to use\nthe [Gradle] plugins DSL in [Kotlin]. Just replace the `$version` variable by\nthe [latest version](#kotools-samples) or by another one available in the\n[changelog](CHANGELOG.md).\n\n```kotlin\nplugins {\n    id(\"org.kotools.samples\") version \"$version\"\n}\n```\n\nSee [this plugin on the Gradle Plugin Portal][kotools-samples-plugin] for more\ninstallation options.\n\n\u003e The `org.kotools.samples.jvm` plugin is deprecated (see\n\u003e [#42](https://github.com/kotools/samples/issues/42)).\n\n## 🧑‍💻 Usage example\n\nKotools Samples ensures that your code samples are integrated into your\ndocumentation without affecting your main sources. For doing so, it creates a\nsource set named `sample` dedicated for code samples.\n\nHere's a [Kotlin] sample:\n\n```kotlin\n// File location: src/sample/kotlin/IntSample.kt\n\nimport kotlin.test.Test\n\nclass IntSample {\n    @Test\n    fun addition() {\n        val x = 1\n        val y = 2\n        check(x + y == 3)\n    }\n}\n```\n\nReference this sample in your [Dokka] documentation:\n\n```kotlin\n// File location: src/main/kotlin/Int.kt\n\n/**\n * Performs an addition with [x] and [y] integers (`x + y`).\n *\n * SAMPLE: [IntSample.addition]\n */\npublic fun addition(x: Int, y: Int): Int = x + y\n```\n\nHere's the documentation generated by [Dokka] with Kotools Samples:\n\n![Screenshot](projects/demonstration/screenshot.png)\n\n## ✅ Supported constructs\n\nKotools Samples offers powerful features for writing expressive samples and\nintegrating them into the documentation.\n\n### 🧪 Sample sources\n\nThis Gradle plugin is able to extract the body of member functions, which can be\nan expression body, even from multiple classes located in the same file. In case\nof empty body, it extracts a placeholder indicating that the sample is not yet\nimplemented.\n\nTop-level functions being incompatible with the `@Test` annotation from Kotlin,\nthey are not supported. This is for ensuring that all samples are testable.\n\n```kotlin\npackage samples\n\nimport kotlin.test.Test\n\nclass FirstSample {\n    @Test\n    fun body() {\n        val x = 1\n        val y = 2\n        check(x + y == 3)\n    }\n\n    @Test\n    fun expressionBody(): Unit = check(1 + 2 == 3)\n}\n\nclass SecondSample { // Multiple classes in single file is supported.\n    @Test\n    fun empty() {} // Placeholder: TODO(\"Sample is not yet implemented.\")\n}\n```\n\n### 🎯 Main sources\n\nFor integrating samples into the documentation, this plugin supports KDoc\ncomments with one or multiple lines, containing one or more sample references.\n\n```kotlin\n/** SAMPLE: [samples.FirstSample.body] */\nfun singleLineKDoc() = Unit\n\n/**\n * SAMPLE: [samples.FirstSample.body]\n */\nfun multiLineKDoc() = Unit\n\n/**\n * SAMPLE: [samples.FirstSample.body]\n * SAMPLE: [samples.FirstSample.expressionBody]\n */\nfun multipleSamples() = Unit\n```\n\n## 📝 Documentation\n\nHere's additional documentation for learning more about this project:\n\n- [Dependency compatibility](documentation/dependencies.md)\n- [Security Policy](SECURITY.md)\n\n## 🤝 Community\n\nJoin our thriving community! Connect, share insights, and collaborate with\nfellow developers to make Kotools Samples even more powerful.\n\n- [#kotools on Kotlin Slack](https://kotlinlang.slack.com/archives/C05H0L1LD25)\n\n## 📣 Show Your Support\n\nIf you find this project valuable, show your support by giving us a ⭐️ on\nGitHub. Your feedback and engagement mean the world to us!\n\n## 🚧 Contributing\n\nContributions are welcome! Feel free to submit bug reports, feature requests, or\npull requests to improve the plugin.\n\n## 🙏 Acknowledgements\n\nThanks to [Loïc Lamarque][@LVMVRQUXL] for creating and sharing this project with\nthe open source community.\n\nThanks to all the [people that ever contributed][kotools-samples-contributors]\nthrough code or other means such as bug reports, feature suggestions and so on.\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE.txt).\n\n\u003c!------------------------------- Shared links --------------------------------\u003e\n\n[@LVMVRQUXL]: https://github.com/LVMVRQUXL\n[dokka]: https://kotl.in/dokka\n[dokka-badge]: https://img.shields.io/badge/Dokka-v2.0.0-blue\n[gradle]: https://gradle.org\n[gradle-badge]: https://img.shields.io/badge/Gradle-v8.12.1-blue?logo=gradle\n[java]: https://www.java.com\n[java-badge]: https://img.shields.io/badge/Java-v17-blue\n[kotlin]: https://kotlinlang.org\n[kotlin-badge]: https://img.shields.io/badge/Kotlin-v2.0.21-blue?logo=kotlin\n[kotools-samples-badge]: https://img.shields.io/github/v/release/kotools/samples?label=Latest\n[kotools-samples-contributors]: https://github.com/kotools/samples/graphs/contributors\n[kotools-samples-plugin]: https://plugins.gradle.org/plugin/org.kotools.samples\n[kotools-samples-releases]: https://github.com/kotools/samples/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotools%2Fsamples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkotools%2Fsamples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotools%2Fsamples/lists"}