From 71e5e5580ba1847230cebdbd6ecf608f6b2cb25f Mon Sep 17 00:00:00 2001 From: Lukasz Kalnik Date: Tue, 11 Jan 2022 18:07:53 +0100 Subject: [PATCH 1/2] Add the Knit annotation requirement to doc snippet policies --- CONTRIBUTING.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1dfc507fbe8..3d6abbdfa0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ use the following priority check list: #### 1. Snippets for public API docs -If the snippet is just docs for a public method of a type (as in arguments, return type, or how it should be used from call sites), that should be inlined in the Kdocs of that given method using Dokka. That's done under the actual type file. [Here you have a simple example for `Option` methods](https://github.com/arrow-kt/arrow/blob/11a65faa9eed23182994778fa0ce218b69bfc4ba/modules/core/arrow-core/src/main/kotlin/arrow/core/Option.kt#L14). +If the snippet is just docs for a public method of a type (as in arguments, return type, or how it should be used from call sites), that should be inlined in the Kdocs of that given method using Dokka and annotated with Knit (see above for more details). That's done under the actual type file. Here you have [a simple example for `Option` type](https://github.com/arrow-kt/arrow/blob/8659228f06bb44b2ea42d18b97d3dc0bdf424763/arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Option.kt#L19). That will automatically inline the docs of each method into the docs of the given data type. This is intended to be used just for public APIs exposed to users of the library. @@ -104,29 +104,35 @@ Public docs in Arrow follow a particular structure that ensures users have a sim Declarations including classes, functions, and others must include docs in the following structure: -All Kdocs should include a short header that describes what the data type or function is for and a triple backticks ``` fenced block demonstrating its use +All Kdocs should include a short header that describes what the data type or function is for and a triple backticks ``` fenced block demonstrating its use (ending with an appropriate Knit annotation) for example ```kotlin /** - * [Refined] is an Abstract class providing predicate validation in refined types companions. - * - * The example below shows a refined type `Positive` that ensures [Int] is > than 0. + * (...) + * + * `Option` is a container for an optional value of type `A`. If the value of type `A` is present, the `Option` is an instance of `Some`, containing the present value of type `A`. If the value is absent, the `Option` is the object `None`. * * ```kotlin - * import arrow.refinement.Refined - * import arrow.refinement.ensure + * import arrow.core.Option + * import arrow.core.Some + * import arrow.core.none * - * @JvmInline - * value class Positive /* private constructor */ (val value: Int) { - * companion object : Refined(::Positive, { - * ensure((it > 0) to "$it should be > 0") - * }) + * //sampleStart + * val someValue: Option = Some("I am wrapped in something") + * val emptyValue: Option = none() + * //sampleEnd + * fun main() { + * println("value = $someValue") + * println("emptyValue = $emptyValue") * } * ``` - */ -abstract class Refined + * + * + * (...) + */ +public sealed class Option { ``` #### 2. Snippets for broader samples @@ -241,10 +247,10 @@ Execution failed for task ':arrow-core:apiCheck'. +++ /Users/john/projects/arrow/arrow-libs/core/arrow-core/build/api/arrow-core-retrofit.api ``` -To make the check pass you need to run: +To make the check pass you need to run the `apiDump` task in the subproject which API you modified (here `arrow-core` as example): ```bash -./gradlew apiDump +./gradlew :arrow-core:apiDump ``` This will generate updated `.api` files which you can then manually review (if the API changes are the ones you intended) and commit and push for the Arrow maintainers to review as well. From e93e1085888dce852b1d7b6c91a7d6a5f19c24fb Mon Sep 17 00:00:00 2001 From: Lukasz Kalnik Date: Wed, 12 Jan 2022 14:48:27 +0100 Subject: [PATCH 2/2] Remove unnecessary info about running apiDump for a subproject --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d6abbdfa0a..07a81f32531 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -247,10 +247,10 @@ Execution failed for task ':arrow-core:apiCheck'. +++ /Users/john/projects/arrow/arrow-libs/core/arrow-core/build/api/arrow-core-retrofit.api ``` -To make the check pass you need to run the `apiDump` task in the subproject which API you modified (here `arrow-core` as example): +To make the check pass you need to run: ```bash -./gradlew :arrow-core:apiDump +./gradlew apiDump ``` This will generate updated `.api` files which you can then manually review (if the API changes are the ones you intended) and commit and push for the Arrow maintainers to review as well.