<@U0AAQKT9Q> I’ve tried but no luck yet. See <http://holgerbrandl.github.io/krangl/javadoc/krangl/kr...

# build-tools

[holgerbrandl]

@ilya.gorbunov I’ve tried but no luck yet. See http://holgerbrandl.github.io/krangl/javadoc/krangl/krangl/builder.html for the result, and for the corresponding source https://github.com/holgerbrandl/krangl/blob/master/src/main/kotlin/krangl/Builder.kt#L45 . From what I can see the referenced sample should be fine as well (see https://github.com/holgerbrandl/krangl/blob/master/src/main/kotlin/krangl/samples/DokkaSamples.kt#L13)

[ilya.gorbunov]

Does the output of dokka task give any clue?

[ilya.gorbunov]

I suppose you need to configure that task a little bit beyond minimal configuration, namely specify where to look for samples.

[holgerbrandl]

So is it not considering gradle’s source sets as a default?

[holgerbrandl]

Thanks @ilya.gorbunov for your help.
First thing I’ve noticed is that it is not cleaning generated docs on “gradle clean” (not sure if it should?!). So to run it again, I always have to clean manually.

Second, concerning the dokka output: it output does not indicate any issues with my @sample in the gradle logs when running the dokka task

Third tooling could be better, that is in Intellij it would be great to be able to jump to the referenced code bit by clicking on it (mockup:

https://i.imgur.com/d8VtklB.png▾

). By doing so, missing/incorrect references could be highlighted in red.

Feel welcome to point me to any tickets I could vote for/comment on.

[orangy]

@semoro ^^

[ilya.gorbunov]

@holgerbrandl I've checked out your project and played with it a bit.
First, note that multiline doc comments should have * on each line, otherwise they are not parsed correctly in IDE:

/**
 * @sample krangl.samples.buildDataFrameof
 */

Actually Ctrl+Click starts working as soon as you're using this format.

[ilya.gorbunov]

Second, it may be not a good idea to place samples in the production source root, try to place them in the tests source set, or even in some custom source set. Then you'll need to specify path to samples in dokka configuration.

[holgerbrandl]

Indeed prefixing javadoc with * enables tooling. Works like charm now! 🙂

The other issue was that I used “Copy Reference” in Intellij to obtain the reference to the sample method (which is just a package level function and not a class member function). However this gives krangl.samples.DokkaSamplesKt.buildDataFrameof instead of the expected/correct krangl.samples.buildDataFrameof. I guess thats more a kotlin plugin bug, not sure if there’s a ticket for it.

For sure the samples should not sit in the production root, but I wanted a working setup before moving them around. Now they are part of test. Thanks a lot for your help.

[orangy]

Please file an issue for “Copy Reference”

[holgerbrandl]

done see https://youtrack.jetbrains.com/issue/KT-21216