search

tnorbye / kdoc-formatter

Reformats Kotlin KDoc comments, reflowing text and other cleanup, both via IDE plugin and command line utility
Apache License 2.0
73 stars 3 forks source link

readme

KDoc Formatter

Reformats Kotlin KDoc comments, reflowing text and other cleanup, both via IDE plugin and command line utility.

This tool reflows comments in KDoc; either on a file or recursively over nested folders, as well as an IntelliJ IDE plugin where you can reflow the current comment around the cursor.

Here's an example of the plugin in use, showing editing a comment and then applying the formatting action to clean it up:

Screenshot

In addition to general cleanup, this is also handy when you're editing a comment and you need to reflow the paragraph because the current line is too long or too short:

Screenshot

Features

Command Usage

$ kdoc-formatter
Usage: kdoc-formatter [options] file(s)

Options:
--max-line-width=<n>
     Sets the length of lines. Defaults to 72.
--max-comment-width=<n>
    Sets the maximum width of comments. This is helpful in a codebase
    with large line lengths, such as 140 in the IntelliJ codebase.
    Here, you don't want to limit the formatter maximum line width
    since indented code still needs to be properly formatted, but you
    also don't want comments to span 100+ characters, since that's less
    readable. Defaults to 72 (or max-line-width, if set lower than 72.)
--hanging-indent=<n>
    Sets the number of spaces to use for hanging indents, e.g. second
    and subsequent lines in a bulleted list or kdoc blog tag.
--convert-markup
     Convert unnecessary HTML tags like < and > into < and >.
--no-convert-markup
     Do not convert HTML markup into equivalent KDoc markup.
--add-punctuation
    Add missing punctuation, such as a period at the end of a
    capitalized paragraph.
--single-line-comments=<collapse | expand>
    With `collapse`, turns multi-line comments into a single line if it
    fits, and with `expand` it will always format commands with /** and
    */ on their own lines. The default is `collapse`.
--align-table-columns
     Reformat tables such that the |column|separators| line up
--no-align-table-columns
     Do not adjust formatting within table cells
--order-doc-tags
    Move KDoc tags to the end of comments, and order them in a canonical
    order (@param before @return, and so on)
--no-order-doc-tags
     Do not move or reorder KDoc tags
--overlaps-git-changes=<HEAD | staged>
    If git is on the path, and the command is invoked in a git
    repository, kdoc-formatter will invoke git to find the changes
    either in the HEAD commit or in the staged files, and will format
    only the KDoc comments that overlap these changes.
--lines <start:end>, --line <start>
    Line range(s) to format, like 5:10 (1-based; default is all). Can be
    specified multiple times.
--include-md-files
     Format markdown (*.md) files
--greedy
    Instead of the optimal line breaking normally used by
    kdoc-formatter, do greedy line breaking instead
--dry-run, -n
    Prints the paths of the files whose contents would change if the
    formatter were run normally.
--quiet, -q
     Quiet mode
--verbose, -v
     Verbose mode
--help, -help, -h
     Print this usage statement.
@<filename>
     Read filenames from file.

kdoc-formatter: Version 1.6.5
https://github.com/tnorbye/kdoc-formatter

IntelliJ Plugin Usage

Install the IDE plugin. Open up the KDoc Formatting Options and inspect the settings to see if you want to change any of the options. By default, KDoc Formatter will use the line width configured for in the Kotlin editor code style for line breaking, but it will also look up the Markdown line width (typically 72) and use that as the maximum comment width. This means that by default, comments will be at most 72 characters wide, even when using a code style which for example breaks at 140 characters.

This is deliberate; comments are optimized for readability, and very long lines are not very readable -- which is why books are typically printed in portrait orientation, not landscape orientation.

The code style line width is used to make sure that when the comment is in deeply nested code, it will still break comments into even shorter lines such that no line goes beyond the line limit.

(Note that if your project uses .editorconfig files to specify indentation, those will be used instead of the Codestyle settings.)

Screenshot

Other options here allow you to for example enable the option to add punctuation where it's missing, or to turn off features such as conversion of HTML tags into KDoc markup.

The KDoc Formatter plugin integrates into the IDE's formatting actions, so if you reformat (for example via Code > Reformat Code), the comment will be reformatted along with the IDE's other code formatting.

You can disable this in options, and instead explicitly invoke the formatter using Code > Reformat KDoc. You can configure a keyboard shortcut if you perform this action frequently (go to Preferences, search for Keymap, and then in the Keymap search field look for "KDoc", and then double click and choose Add Keyboard Shortcut.

Screenshot

The plugin is available from the JetBrains Marketplace at https://plugins.jetbrains.com/plugin/15734-kotlin-kdoc-formatter

Gradle Plugin Usage

The plugin is not yet distributed, so for now, download the zip file and install it somewhere, then add this to your build.gradle file:

buildscript {
    repositories {
        maven { url '/path/to/m2' }
    }
    dependencies {
        classpath "com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.4"
        // (Sorry about the vanity URL --
        // I tried to get kdoc-formatter:kdoc-formatter:1.6.4 but that
        // didn't meet the naming requirements for publishing:
        // https://issues.sonatype.org/browse/OSSRH-63191)
    }
}
plugins {
    id 'kdoc-formatter'
}
kdocformatter {
    options = "--single-line-comments=collapse --max-line-width=100"
}

Or in build.gradle.kts:

buildscript {
    repositories {
        maven { url = uri("/path/to/m2") }
    }
    dependencies {
        classpath("com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.4")
    }
}
plugins {
    id("kdoc-formatter")
}

Here, the [options] property lets you use any of the command line flags from the kdoc-formatter command.

Building and testing

To create an installation of the command line tool, run

./gradlew install

The installation will be located in cli/build/install/kdocformatter.

To create a zip, run

./gradlew zip

To build the plugin, run

./gradlew :plugin:buildPlugin

The plugin will be located in plugin/build/distributions/.

To run/test the plugin in the IDE, run

./gradlew runIde

To reformat the source tree run

./gradlew format

To build the Gradle plugin locally:

cd gradle-plugin
./gradlew publish

This will create a Maven local repository in m2/ which you can then point to from your consuming projects as shown in the Gradle Plugin Usage section above.