Use @sample block tags in KDoc to embed samples inside the API

[uzilan]

Platform (all, jvm, js, android): all
Extension (none, kotlin 1.3): none

Code related feature

/**
 * Expects that the subject of the assertion is (equal to) [expected].
 *
 * @return An [Expect] for the current subject of the assertion.
 * @throws AssertionError Might throw an [AssertionError] if the assertion made is not correct.
 * @sample org.atriumlib.samples.junit5.SampleJvmTest.`to be`
 */
infix fun <T> Expect<T>.toBe(expected: T): Expect<T> = _logicAppend { toBe(expected) }

Non-Code related feature

Is your feature request related to a problem? Please describe.
Looking at the Atrium documentation, it is not always simple to understand how to use certain assertions, especially if they are complex. An example might make life easier.

Describe the solution you'd like
the @sample block tag could be used in the API documentation to refer to the samples in the sample projects. Those samples will then be included in the project's documentation and will make it easier for users of Atrium to see how to use the various assertions by looking at samples rather than trying to understanding the specifications.

The Kotlin standard library is using those @sample block tags extensively and have asked for help adding samples to make the API easier. I think it's a great way to help users understand the API and since you already have samples in the Atrium project it should be easy enough to simply refer to them using @sample.

[robstoll]

@uzilan I had this on my roadmap but didn't find the time to look deeper into it. Note that the samples in README are generated via ReadmeSpec but they have a different goal I would say as they serve to demonstrate the error message as well. A sample per function in KDoc would be great.

Last time I had a look, the samples for @sample needed to be in src/main. Something I don't like that all. If that's no longer a requirement, then go ahead. Would you be interested to write a prototype?

[uzilan]

@robstoll the samples in the kotlin std lib can be found under kotlin/libraries/stdlib/samples/test/samples/ so I guess it's sorted. I'd like to help adding the @samples in Atrium but am having a tough time figuring out how to refer to the functions in the samples projects from the API. I guess a reference has to be added in the root settings.gradle file but I'm afraid my gradle skills are limited, so I wonder if you can give me a hint.

[robstoll]

Sounds good and nice that you want to improve Atrium here 👍

The samples folder is not the right place, those are sample projects which one can copy as a start.
We want to have samples per API. As a start I would try to add a sample to the fluent API, thus put the samples to apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples. I suggest you start with anyAssertions.kt

[uzilan]

Ok cool, I'll give it a try.

[robstoll]

@uzilan I had a look by myself in the meantime. I am going to create dedicated issues per file. Therefore I am closing this issue. Would be nice if you could contribute some of the samples.

[uzilan]

@robstoll sure, I also started a bit but got stuck because I couldn't get Dokka to include the samples. Maybe you have an idea how to solve it?

[robstoll]

@uzilan you can have a look at my PR to see how I did it: #642