Support for Kotlin's documentation format KDoc

[nailgilaziev]

Hi! When I first time heard about spring rest doc, I thought it would be ideal to generate content from javadocs. At first I was a little bit disappointed when I understood how it works, but then I found your library. This is the right approach to generate documentation, because I have documended my code via Kdoc(javadoc extension) - https://kotlinlang.org/docs/reference/kotlin-doc.html Now I want try it, but can you say, can it work with kotlin?

[nailgilaziev]

If I document it like this

/**
 * Class desc Jenkins job
 * @property platform desc
 * @property project desc
 * @property state desc
 * @property message desc
 * @property logs  desc
 */
data class JobState(        
        val project: String,
        val state: String,
        val message: String,
        val logs: String?
)

[fbenz]

KDoc is different from Javadoc and currently we only provide a Javadoc to JSON processor. There might be a way to transform KDoc so that our Javadoc doclet can work with it. Otherwise, one would have to write a KDoc to JSON transformer.

[jmisur]

Unfortunately we're not developing with Kotlin (yet), so any implementation would need to be outsourced - please create a pull request with proposed implementation and we can have a look and provide support to you.

[nailgilaziev]

hi! tell me, please, your attitude to this issue has not changed over time? are you have any plans to add this enhancement in the future?

[fbenz]

I'm actually looking into this again. Looks like we have to extend Dokka and add a custom JSON format. Dokka is able to process both Javadoc and KDoc and with such an extension it would be possible to use Spring Auto REST Docs for mixed Java/Kotlin or pure Kotlin projects. Current status is that I'm playing around with Dokka.

[pnowy]

@nailgilaziev which tool are you using for build with kotlin - maven or gradle? Could you share your jsonDoclet configuration if you are using gradle. Unfortunately I'm trying to use it with gradle 4.X with kotlin and options.docletpath definition cause the problem during scanning project dependencies (just broke the build that cannot find totaly different dependency what is weird). Did you notice any problem with it?

Thanks

[nailgilaziev]

I'm using gradle build tools, but for now, I'm not using any jsonDoclet configuration, so I can't give advice on this problem

[pnowy]

Well I bypass the problem when I replace the

options.docletpath = configurations.jsondoclet.files.asType(List)

to

options.docletpath = [file("libs/spring-auto-restdocs-json-doclet-1.0.11.jar")]

Of course still there is a problem with parsing (Illegal package name)

[fbenz]

@nailgilaziev The KDoc to Spring Auto REST Docs' JSON converter was released just now. See https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-dokka-json It works with both Spring Auto REST Docs 2.0.0 and 1.0.12, because both use the same JSON format. However, version 1.0.12 does not document not-null fields yet, but that should be supported in the next release. Please let me know whether it works for you. We only tested it on a limited number of projects so far.