Kotlin Documentation and HTML Tags

The Issue with `

` Tags

Kotlin’s documentation system, KDoc, has limited support for HTML tags, specifically the `

` tag. While other tags like `

`, `

`, and `

` function correctly, `

` tags are often ignored, leading to unexpected formatting and layout issues.

Impact on Documentation

This limitation presents several challenges for developers:

* **Poor readability:** Without paragraph breaks, documentation can become a dense block of text, making it difficult to read and understand.
* **Inconsistent formatting:** The lack of `

` support leads to inconsistent formatting across different documentation sections, affecting the overall aesthetic and clarity.
* **Limited styling options:** Without proper paragraph separation, it’s difficult to apply styles and achieve desired visual effects.

Alternatives to `

`

While `

` tags are not fully supported, there are alternatives for achieving paragraph breaks and formatting:

* **Line breaks:** Multiple consecutive line breaks can be used to create paragraph-like separations.
* **Empty lines:** Leaving an empty line between blocks of text can also visually separate paragraphs.
* **HTML comments:** While not ideal, using HTML comments like `` can be used to create empty lines for visual separation.

Example:

**Incorrect Code:**

“`pre
/**
* This is a long description that should be broken
* into multiple paragraphs for better readability.

* However, the

tag is ignored by KDoc.
*/
“`

**Correct Code:**

“`pre
/**
* This is a long description that should be broken
* into multiple paragraphs for better readability.
*
* However, the `

` tag is ignored by KDoc.
*/
“`

Comparison Table:

| Feature | KDoc Support |
|—|—|
| `

` tag | **No** |
| `

` tag | **Yes** |
| `

` tag | **Yes** |
| `

` tag | **Yes** |
| Line Breaks | **Yes** |
| Empty Lines | **Yes** |

Conclusion

While KDoc’s limited support for `

` tags presents challenges, developers can utilize alternatives like line breaks, empty lines, or HTML comments to achieve visual separation and improve documentation readability. However, it’s important for JetBrains to address this limitation and enhance KDoc’s HTML support for a more comprehensive and user-friendly documentation experience.