Hey everyone! Not a Dokka-related question but thi...

# dokka

[Nishant Aanjaney Jalan]

Hey everyone! Not a Dokka-related question but this is of KDoc. The @sample tag described here is not fully descriptive of how to include a sample function. Can someone give me an example? Do you think it's good have an issue to improve the KDoc Docs?

[CLOVIS]

I don't have an example on hands, but the idea is:

• you create a function somewhere in your code (e.g. in src/test/kotlin)
• you tell Dokka that the source set in which that function is declared is where samples are (it's somewhere in the Gradle config)
• then, you can use @sample <http://fully.qualified.name.to|fully.qualified.name.to>.Your.function
However, it's not a very useful feature at the moment, because in the HTML output it will generate a Kotlin Playground snippet, with a 'run' button, but since the Kotlin Playground doesn't let you import your own libraries, running it will always fail 😕

[CLOVIS]

@Loïc Lamarque showed me something interesting to help with this, but I don't know if it's public yet 👀

[Nishant Aanjaney Jalan]

Ohh that's actually sad. I was thinking to have a samples module inside my library repo that contains all example code and reference them in my library docs. So my tests are separate from src and also separate from samples. Do you think it's a good idea for KDoc? I am happy to put this issue on youtrack too.

[CLOVIS]

AFAIK it needs to be a source set, not a project.

But you could create an additional source set so it looks like

src/
  main/…
  test/…
  samples/…

I don't know the config for that from memory, but you need to create a new Configuration to hold the dependencies, ensure it has a dependency on main , then create a SourcetSet from that Configuration

[CLOVIS]

But you'd still have the problem that the generated Playground snippets won't run 😕

[Nishant Aanjaney Jalan]

Oh that makes sense. Yeah that is great as well. I'll wait for Loic's reply if the sourceset configuration is public or not. Thank you!

But you'd still have the problem that the generated Playground snippets won't run

That's okay for now, I can put a disclaimer in my documentation. Atleast that would be formatted nice with good syntax highlighting at the very least.

[CLOVIS]

To be fair, if you just use triple backticks + kotlin , you will get syntax highlighting as well (example). However, since it's just text and not actual code, it's easy to miss it being out of date 😕

[Adam S]

in case it helps: it should be possible to test code blocks in kdoc with https://github.com/Kotlin/kotlinx-knit

[CLOVIS]

@Adam S tell me if I'm wrong, but the last time I looked into it, it required copy-pasting all samples in a different place and thus committing them twice?

[Adam S]

tbh I haven't used the kdoc validation, but I believe it works similar to the Markdown validation. In which case, yes, the files are committed twice, but you don't need to copy paste them, Knit automatically extracts the samples into separate files

[Adam S]

but please correct me if I'm wrong

[CLOVIS]

Well, do what you want, but I personally really dislike this way of handling things.

[Michael Krussel]

I believe there is a way to install your library on your server and configure the playground to use it. I remember experimenting with the samples years ago and getting something to work, but not the details of how.

[Loïc Lamarque]

Hello everyone! Thank you @CLOVIS for tagging me on this thread.

@Nishant Aanjaney Jalan I found a solution for linking source code as Dokka readonly samples. You can find an example of what it looks like in the API reference of Kotools Types, a library providing explicit types that I'm maintaining. The solution is not public yet, but will be available as a Gradle plugin for easy integration with Kotlin projects. The idea behind the solution, is to be able to provide the sample once in a dedicated source set, with unit tests for making sure that the sample is always up-to-date, then referencing it from the documented declaration in the main source. This link will allow the Gradle plugin to generate the according HTML documentation using Dokka.

If you are interested in this Gradle plugin, please react to this message so I can put some effort in making this project publicly available as soon as possible for the community.
Also, any name idea is welcomed. 😁

[CLOVIS]

kdoc-test?

[Loïc Lamarque]

@CLOVIS I don't know if kdoc-test fits for that project. This naming seems like the main focus is testing the documentation, which is not. The goal is to provide a mechanism for integrating readonly and testable samples in KDoc.

What do you think about kdoc-samples ?

[CLOVIS]

I was taking inspiration from https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html, but I'm not good at naming things 😅

[Loïc Lamarque]

I didn't know that Rust has this documentation test mechanism. That's interesting. I will keep the name in mind @CLOVIS. 👀

[CLOVIS]

Yeah, I always wanted Dokka to have that. Being able to run samples as unit tests is great.

However, the Rust implementation has a few downsides. First, dependency management in Rust-land is far from being as advanced as Gradle, so "what dependencies are available in samples" is a bit ambiguous. Also, each sample runs in its own binary, that has to be compiled, linked, etc, which is SLOW.

I would much prefer a

src/
  main/…
  test/…
  sample/…

structure so samples are clearly separate, have clear dependencies, etc.

However, the part with having a way to hide parts of the code from the samples is very important. The # syntax would probably require a lot of work to get working, but I'd be happy with something like

@Test
fun `sample for filter`() {
    // region hide
    val list = listOf(1, 2, 3, 4)
    // endregion
    list.filter { it % 2 == 0 }
}

When using this sample, only the last line would be part of the actual documentation

[CLOVIS]

Hm, I don't get why it would be another project instead of a source set. Also, making the samples JVM-only is a problem I think, at some point you'll want to have samples for non-JVM platforms.

Also, I don't think you need all that boilerplate. The sample could be the test itself if you use `check`inside of it.

[Loïc Lamarque]

@CLOVIS Does the check function should be shown in the documentation? I would love to remove that boilerplate, so I'm kind of interested by your suggestions. 👀

[CLOVIS]

Hmmm

[CLOVIS]

What do you think, are documentation tests meant to test the behavior of the function, or just test that it still compiles?

[Michael Krussel]

From what I remember from years ago was that the check would be aliased to an assert in the unit tests and a println in the samples source set. I don't remember how it was done though.

[Loïc Lamarque]

@CLOVIS In my opinion, the ultimate goals of providing a testable sample in the documentation, in addition to showing how to use the documented declaration, are the followings:
• Test that the syntax of the sample is correct (through compilation)
• Test that the behavior of the documented declaration is correct (though unit test).

[Loïc Lamarque]

@Michael Krussel I saw that in the Kotlin language repository, but I don't know how this magic happens. 😅

[CLOVIS]

• Test that the behavior of the documented declaration is correct (though unit test).

I think this is debatable. Some people will want tests to be part of the documentation, some won't.

Since your version puts sample code directly in a proper source set, I wouldn't mind either way

[CLOVIS]

^ that was, as a library author.

As a developer looking through the documentation, I honestly don't know if I want to see check /`assert` etc. Maybe that would be worth asking people about it in #feed?

[Loïc Lamarque]

@CLOVIS As a consumer looking through the documentation, this is kind of unusual to see check or assert* functions, but it seems to be a good idea for reducing boilerplate by executing the sample as a test. If seeing assertions in the documentation is disturbing, it could be possible to hide them using region tokens, like you've suggested earlier in this thread.

[CLOVIS]

I wonder if you could have a small routine that replaces

check(foo.bar == "my output")

to

println(foo.bar) // "my output"

automatically when generating the documentation 🤔

[Loïc Lamarque]

This could be possible @CLOVIS, but why doing this extra work when generating the documentation, which is already a demanding task?
In my opinion, there is no value in doing such, because both code have the same meaning in the documentation.

[CLOVIS]

Fair.

[CLOVIS]

The Rust community is used to havnig assert_eq in documentation examples, so I don't think it's particularly harder to read

[CLOVIS]

To be honest, having examples in the documentation at all is not that much common in the Kotlin ecosystem, so…

[CLOVIS]

Well, the answer can be as simple as "the library author decides. If they want to use check , nothing's stopping them"

Personally, I probably won't put assertions in my documentation (I just want to ensure it compiles, I have proper tests to ensure behavior).

[Loïc Lamarque]

To be honest, having examples in the documentation at all is not that much common in the Kotlin ecosystem, so…

@CLOVIS Meaning that having read-only samples in the documentation would already be a massive improvement. 😉

[CLOVIS]

I know 😅

I have a very large library coming that I can't announce yet, I'm committing to at least one example for each function, and let me tell you, I'm worried of the next refactor. I'm not checking them manually to see if I forgot something.

[Michael Krussel]

Kotiln itself has a lot of executable samples, but they are in their documentation and not API reference.

[Loïc Lamarque]

I have a very large library coming that I can't announce yet, I'm committing to at least one example for each function, and let me tell you, I'm worried of the next refactor. I'm not checking them manually to see if I forgot something.

I have to grind on that thing for you then @CLOVIS. 👀

Kotiln itself has a lot of executable samples, but they are in their documentation and not API reference.

Yes @Michael Krussel, but doing the same with another library than the Kotlin standard one very hard to do: the playground doesn't seem to include custom JARs in the compilation. That's currently the pain point.

[CLOVIS]

Yeah. Dokka generates working Playground snippets, but they cannot compile because the Playground doesn't have your library 😕

[CLOVIS]

Also, Dokka only puts the samples at the end of the text. I really want to have samples in the middle of text, so I can explain what it does.

[Loïc Lamarque]

It will be supported by the tool starting on the first release @CLOVIS. 👀

[CLOVIS]

Do you have an idea where that will be?? On my side, I'm targeting a public release (beta-quality) in ~october.

[Loïc Lamarque]

@CLOVIS I'm doing my best to work on this for releasing it publicly as soon as possible, accordingly what was said in this thread. October seems to be a realistic deadline though. 👀

[Nishant Aanjaney Jalan]

I didn't get any email notifications. I am completely out of touch with this thread, but I like the development. Thanks @Loïc Lamarque for your work with generating the samples. It will be great to see what can be done with this.

[Nishant Aanjaney Jalan]

@Michael Krussel I think [this](https://stackoverflow.com/a/64396542/11292068) is what you were referencing

[Nishant Aanjaney Jalan]

The problem is that it is a localhost server and you'd have to host it somewhere

[Loïc Lamarque]

Your welcome @Nishant Aanjaney Jalan. I will let you know when the tool will be available for trying it out if you are interested. 🙂

[Loïc Lamarque]

@Nishant Aanjaney Jalan As promised, Kotools Samples 0.1.0 is available for inlining read-only code samples in your documentation. Feedbacks about this Gradle plugin are very welcome. 😁