Make possible to use @sample in the module .md file

[jaguililla]

No description provided.

[semoro]

No, but you can include simple code blocks by using backticks

[jaguililla]

Ok... I was asking because if that was possible, the code embedded in the documentation could be tested (picked from a test) and documentation would be correct :)

Do you think it is worthy to convert this to an issue?

And thanks for the information! :)

[MariusVolkhart]

(adding my details to this)

Is your feature request related to a problem? Please describe
I'm using a .md file to document my package, as described at https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation

I'd like to include a code sample/snippet of how the classes in the package fit together.

Describe the solution you'd like
I'd like functionality similar to the @sample KDoc block tag, so that I can write code in a .kt file that gets compiled and tested, but then gets merged into the resulting documentation.

Describe alternatives you've considered
One option is to write the code sample inline as markdown. This has the downside of being untestable and having no code completion or refactoring support.

This can be slightly improved by maintaining 2 copies of the sample: one in the markdown, the other as code. However, it is then up to developers to know to update both locations when making changes.

Additional context
The DocFX tool supports this sort of code referencing

[deniskr]

No, but you can include simple code blocks by using backticks

backticks do not work either, as of Gradle plugin version 1.4.0-rc

[anti-social]

Tried to include code sample in markdown. Single @sample works fine, but multiple does not:

modules.md:

# Module dokkasamples

The module shows the Dokka syntax usage.

## Getting started

@sample samples.sample1

@sample samples.sample2

$ ./gradlew dokkaHtml
...
Unresolved function samples.sample1
 in @sample
Cannot find PsiElement corresponding to samples.sample1

As a result only samples.sample2 renders in documentation.

[TheNullicorn]

For anyone looking for a workaround, I've gotten multiple @sample tags work in a markdown file under these conditions:

• There must be some non-whitespace text between the # Module or # Package heading and the @sample tags
• The functions must be enclosed in some kind of class
  • Objects, interfaces, abstract classes, and enum classes all seem to work
  • Top level functions only seem to allow for 1 sample, and have a lot of strange quirks when multiple are available
• The @sample tags are the last thing in the markdown file

Greetings.kt:

package samples

object Greetings {
    fun formal() {
        println("Hello")
    }

    fun casual() {
        println("What's up?")
    }
}

Greetings.md:

# Package my.package.name

My package overview...

@sample samples.Greetings.formal
@sample samples.Greetings.casual

Output: