Line break, new line in KDoc

Question

Assuming we have such documented string

/** retrieve a state of the service
* <br/> HTTP code 200 - normal state
* <br/> HTTP code 403 - some recoverable state:
const val SERVICE_STATE = "servicestate" */

There are several <br/> here, which i used to break a line, like i do in java, but output of AndroidStudio (seems same in InteliJIdea) is

with java it is parsed & displayed correctly:

/** retrieve a state of the service
 * <br/> HTTP code 200 - normal state
 * <br/> HTTP code 403 - some recoverable state */
public static final String SERVICE_STATE = "servicestate";

Can i somehow achieve the same with kotlin & IntelijIdea, maybe kotlin has another option to break the line in KDoc?

If someone is looking for this, please vote on https://youtrack.jetbrains.com/issue/KTIJ-6702! — TWiStErRob, Jan 20 '23 at 10:54

score 36 · Accepted Answer · edited Jan 20 '23 at 10:55

36

The KDoc format uses Markdown syntax instead of HTML, and basic Markdown does not provide a way to break the line without starting a new paragraph.

^{I'm not sure why the Kotlin IntellIJ plugin does not support <br/> or the double space hack.}

If starting a new paragraph is OK, just skip an empty line:

/** 
 * retrieve a state of the service
 *
 * HTTP code 200 - normal state
 *
 * HTTP code 403 - some recoverable state:
 */

The result is:

edited Jan 20 '23 at 10:55

TWiStErRob

44,762
26
170
254

answered Mar 29 '18 at 14:52

hotkey

140,743
39
371
326

(updated the answer – removed the redundant `
` tags) – hotkey Mar 29 '18 at 14:57
It seems that KDoc doesn't takes the line in the new paragraph. – Lore Nov 15 '19 at 09:04
8

What about leaving an empty line between two code lines? I couldn't find it. – Thracian Sep 13 '20 at 10:40
The double-space is not a hack, it's a feature described in the [documentation](https://daringfireball.net/projects/markdown/syntax#p). – TWiStErRob Jan 20 '23 at 10:40

aksh1618 · Answer 2 · 2022-03-16T12:10:59.170

To add to @hotkey's answer, you can also use triple backticks as Markdown is supported:

/**
 * Returns masked complement, i.e. expected value in the [maskBits] bits instead of a negative number because of
 * 2's complement representation
 *
 * For example, for 9:
 * ```
 *  Binary representation:         00...01001
 *  Complement:                    11...10110 which is -10
 *  Masking with 4 bits:  and with 00...01111
 *  So we get:                     00...00110 which is the expected bitwise complement
 * ```
 * @param maskBits Number of bits to mask the complement to
 * @return Decimal representation of the masked complement
 */
fun Int.inv(maskBits: Int) = inv() and 2.pow(maskBits) - 1

The result is:

score 2 · Answer 3 · answered Oct 03 '22 at 08:48

2

It is possible to use dashes in lists. Empty lines are not needed in this case.

answered Oct 03 '22 at 08:48

macros013

739
9
10

Line break, new line in KDoc

3 Answers3