1 /* 2 * Portions Copyright (c) Meta Platforms, Inc. and affiliates. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /* 18 * Copyright (c) Tor Norbye. 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); 21 * you may not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, 28 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 package com.facebook.ktfmt.kdoc 34 35 import kotlin.math.min 36 37 /** Options controlling how the [KDocFormatter] will behave. */ 38 class KDocFormattingOptions( 39 /** Right hand side margin to write lines at. */ 40 var maxLineWidth: Int = 72, 41 /** 42 * Limit comment to be at most [maxCommentWidth] characters even if more would fit on the line. 43 */ 44 var maxCommentWidth: Int = min(maxLineWidth, 72) 45 ) { 46 /** Whether to collapse multi-line comments that would fit on a single line into a single line. */ 47 var collapseSingleLine: Boolean = true 48 49 /** Whether to collapse repeated spaces. */ 50 var collapseSpaces: Boolean = true 51 52 /** Whether to convert basic markup like **bold** into **bold**, < into <, etc. */ 53 var convertMarkup: Boolean = true 54 55 /** 56 * Whether to add punctuation where missing, such as ending sentences with a period. (TODO: Make 57 * sure the FIRST sentence ends with one too! Especially if the subsequent sentence is separated.) 58 */ 59 var addPunctuation: Boolean = false 60 61 /** 62 * How many spaces to use for hanging indents in numbered lists and after block tags. Using 4 or 63 * more here will result in subsequent lines being interpreted as block formatted by IntelliJ (but 64 * not Dokka). 65 */ 66 var hangingIndent: Int = 2 67 68 /** When there are nested lists etc, how many spaces to indent by. */ 69 var nestedListIndent: Int = 3 70 set(value) { 71 if (value < 3) { 72 error( 73 "Nested list indent must be at least 3; if list items are only indented 2 spaces they " + 74 "will not be rendered as list items") 75 } 76 field = value 77 } 78 79 /** 80 * Don't format with tabs! (See 81 * https://kotlinlang.org/docs/reference/coding-conventions.html#formatting) 82 * 83 * But if you do, this is the tab width. 84 */ 85 var tabWidth: Int = 8 86 87 /** Whether to perform optimal line breaking instead of greeding. */ 88 var optimal: Boolean = true 89 90 /** 91 * If true, reformat markdown tables such that the column markers line up. When false, markdown 92 * tables are left alone (except for left hand side cleanup.) 93 */ 94 var alignTableColumns: Boolean = true 95 96 /** 97 * If true, moves any kdoc tags to the end of the comment and `@return` tags after `@param` tags. 98 */ 99 var orderDocTags: Boolean = true 100 101 /** 102 * If true, perform "alternative" formatting. This is only relevant in the IDE. You can invoke the 103 * action repeatedly and it will jump between normal formatting an alternative formatting. For 104 * single-line comments it will alternate between single and multiple lines. For longer comments 105 * it will alternate between optimal line breaking and greedy line breaking. 106 */ 107 var alternate: Boolean = false 108 109 /** 110 * KDoc allows param tag to be specified using an alternate bracket syntax. KDoc formatter ties to 111 * unify the format of comments, so it will rewrite them into the canonical syntax unless this 112 * option is true. 113 */ 114 var allowParamBrackets: Boolean = false 115 116 /** Creates a copy of this formatting object. */ copynull117 fun copy(): KDocFormattingOptions { 118 val copy = KDocFormattingOptions() 119 copy.maxLineWidth = maxLineWidth 120 copy.maxCommentWidth = maxCommentWidth 121 copy.collapseSingleLine = collapseSingleLine 122 copy.collapseSpaces = collapseSpaces 123 copy.hangingIndent = hangingIndent 124 copy.tabWidth = tabWidth 125 copy.alignTableColumns = alignTableColumns 126 copy.orderDocTags = orderDocTags 127 copy.addPunctuation = addPunctuation 128 copy.convertMarkup = convertMarkup 129 copy.nestedListIndent = nestedListIndent 130 copy.optimal = optimal 131 copy.alternate = alternate 132 133 return copy 134 } 135 } 136