Our application’s internal documentation includes a “guided tour” that takes new developers through the flow of control step by step so they can learn how things fit together. It’s intended to be navigated from inside IntelliJ, not in a web browser, since the point is to skim the code as you follow the tour. In Javadoc we are able to make it really easy to navigate by putting “previous” and “next” {@link}s at the bottom of each stop in the tour.
Now we’re migrating some of our code base to Kotlin and this is a minor sticking point. Some parts of our code use a lot of method overloading. KDoc is, according to its documentation, unable to link to a specific method overload because it wouldn’t make sense in the generated HTML files. Which is fine, but we’re not even generating HTML from our docs at all, just using it from inside IntelliJ.
What’s the recommended Kotlin solution for documentation that’s fully navigable in an IDE (either IntelliJ-specific or general)?