CODEWITHSUNDEEP
documentationkotlinkdoc
humazed
humazed

Reputation: 76962

How to use @link and @code in kotlin kDoc

I'm trying to document a method and trying to use @link and @code as in JavaDoc.

I know in kotlin there is a kDoc but I can't find them or at least something similar.

Upvotes: 178

Views: 92688

Answers (10)

antaki93
antaki93

Reputation: 860

Just use code like this:

import my.package.name.MyClass

/**
 * Click to follow: [MyClass.myField], [MyClass.myMethod]
 */

Upvotes: 0

Michael Piefel
Michael Piefel

Reputation: 19998

The answer that Artur gave is a good hint in general, but the result is wrong. At least IntelliJ IDEA does not grok the result. The markdown link format using []() is fine in the main comment text, but not for external links in the @see tag. For those, you need the same syntax as in Java:

/**
 * Do something.
 *
 * @see <a href="https://stackoverflow.com/q/45195370/2621917">External links in kdoc</a>
 */

The (very brief) documentation for @see suggests that the syntax is supposed to be only @see ‹identifier›, so it seems that it works as intended.

Upvotes: 29

James Bond
James Bond

Reputation: 3016

It seems we should just use a markdown hyperlink without any special tags such as @see or @link:

/**
 * This is a doc.
 *
 * See [this](https://google.com)
 * And [this](https://stackoverflow.com)
 */
fun myfun() {}

This doc renders in following way in IDE:

render of a doc in IDE

Upvotes: 27

Mopto
Mopto

Reputation: 390

Sample how to leave links for classes:

/**
 * [YourClass] Methods
 * */

also with method calls

/**
 * [YourClass.someMothod] Methods
 * */

Real example:

 /**
 * [BaseActivity] Methods
 * */
override fun initVars() {
    //Just Sample
}

/**
 * [MainContract.View] - Overrides
 * */
override fun handleConnectionMassage(isShow: Boolean) {
    //Just Sample
}

Upvotes: 8

hb0
hb0

Reputation: 3777

To reference a method use the class:

/**
 * When the configuration succeeds **[MyCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

Using a variable/parameter does not work:

/**
 * When the configuration succeeds **[myCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

Upvotes: 15

Aryeetey Solomon Aryeetey
Aryeetey Solomon Aryeetey

Reputation: 5835

For {@link SomeClass} in Java maps to [SomeClass] in Kotlin

For {@code true} in Java maps to `true` in Kotlin

Upvotes: 59

Ilya Serbis
Ilya Serbis

Reputation: 22333

As for the @code you should use Markdown syntax (cause KDoc is an extended version of Markdown):

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.

/**
 * Some code sample:
 * 
 *    Set<String> s;
 *    System.out.println(s);
 */
class Scratch

Upvotes: 15

szaske
szaske

Reputation: 2027

I struggled with this for a bit with Android Studio 3.5.2 on Mac. This worked for me:

/**
* [Your fully-qualified class name.function name]
*/

If I didn't use the fully-qualified name Kdoc would complain that it was a unresolved reference. What I couldn't figure out is how to actually use the link itself. For that you need to press and hold the COMMAND key (on Mac) and then the links would be active.

Upvotes: 17

Artur Dumchev
Artur Dumchev

Reputation: 1330

You can write your code with java and convert class into Kotlin.

/**
 * @see <a href="http://somelink.com">link</a>
 */
public class Some {
}

will be converted to

/**
 * @see [link](http://somelink.com)
 */
class Some

Upvotes: 43

humazed
humazed

Reputation: 76962

@link and @code doesn't exist in kDoc but can easily be replaced by Inline Markup.

from KotlinDoc Linking to Elements

Inline Markup

For inline markup, KDoc uses the regular Markdown syntax, extended to support a shorthand syntax for linking to other elements in the code.

Linking to Elements

To link to another element (class, method, property or parameter), simply put its name in square brackets:

Use the method [foo] for this purpose.

If you want to specify a custom label for the link, use the Markdown reference-style syntax:

Use [this method][foo] for this purpose. You can also use qualified names in the links. Note that, unlike JavaDoc, qualified names always use the dot character to separate the components, even before a method name:

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class. Names in links are resolved using the same rules as if the name was used inside the element being documented. In particular, this means that if you have imported a name into the current file, you don't need to fully qualify it when you use it in a KDoc comment.

Note that KDoc does not have any syntax for resolving overloaded members in links. Since the Kotlin documentation generation tool puts the documentation for all overloads of a function on the same page, identifying a specific overloaded function is not required for the link to work.

Upvotes: 220

Related Questions