Support interleaving @samples with other documentation

[owengray-google]

Is your feature request related to a problem? Please describe
In AndroidX and our dokka plugin (and in old dokka), we support inline @sample tags:

https://developer.android.com/reference/android/graphics/Color.html
or this example with new-dokka

We think the ability to interleave code samples with documentation text is extremely valuable to clear explanations.
We strongly discourage the internal use of inline code blocks (e.g. three backticks) because (a) we can't compile the code in those blocks, and it can have errors, (b) we can't compile the code in those blocks against the library they're providing samples for, so changes to the library can make them out of date, and (c) we can't support inline code blocks with our new feature to provide different samples for each KMP platform, or to Kotlin and Java viewers.
(We can do all of those things with samples that use @sample tags.)

However, the kdoc spec lists @sample as a "block tag, which I believe means that, like all of the other block tags, they are supposed to be inserted at the end. It might also mean there is supposed to be at most one--the spec is unclear.

Describe the solution you'd like
Kdoc spec supports inline samples in some way, that work like @sample tags do today.

(a) One possibility would be to simply support @sample tags interleaved with text (possibly requiring their own line); this is what we do

(b) Another possibility would be to add a new syntax for interleaved samples; @sample syntax matches other syntax for tags that get moved to the end of the documentation like @param and @returns.

Additional context
This is becoming an issue for us specifically right now because ktfmt linter moves all kdoc block tags to the end of a member's documentation and sorts them.
If we had a decision from kdoc to support (a), we could approach ktfmt with it. If we had a decision on a syntax for (b), we might be able to migrate out uses and implementation to match--it's not clear how much upstream work this would require to get working for us.