Skip to content

Commit

Permalink
Add @property, @receiver, and @exception to the list of essenti…
Browse files Browse the repository at this point in the history 
…al tags (#1468)

### What's done:

 * All the above KDoc tags are essential because they document the signature of
   a function. Therefore, they should be grouped together with other
   signature-specific tags (`@param`, `@return`, `@throws`).
 * We also include the `@constructor` tag into the list (see, for example, how
   `kotlin.Pair` is documented).
 * This fixes #1465.
  • Loading branch information
@0x6675636b796f75676974687562
0x6675636b796f75676974687562 authored Jul 21, 2022
1 parent ff346b0 commit 054894e
Show file tree
Hide file tree
Showing 3 changed files with 26 additions and 3 deletions.
2 changes: 1 addition & 1 deletion diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ enum class Warnings(
KDOC_WITHOUT_THROWS_TAG(true, "2.1.2", "all methods which throw exceptions should have @throws tag in KDoc"),
KDOC_EMPTY_KDOC(false, "2.1.3", "KDoc should never be empty"),
KDOC_WRONG_SPACES_AFTER_TAG(true, "2.1.3", "there should be exactly one white space after tag name in KDoc"),
KDOC_WRONG_TAGS_ORDER(true, "2.1.3", "in KDoc standard tags are arranged in order @param, @return, @throws, but are"),
KDOC_WRONG_TAGS_ORDER(true, "2.1.3", "in KDoc standard tags are arranged in this order: @receiver, @param, @property, @return, @throws or @exception, @constructor, but are"),
KDOC_NEWLINES_BEFORE_BASIC_TAGS(true, "2.1.3",
"in KDoc block of standard tags @param, @return, @throws should contain newline before only if there is other content before it"),
KDOC_NO_NEWLINES_BETWEEN_BASIC_TAGS(true, "2.1.3", "in KDoc standard tags @param, @return, @throws should not containt newline between them, but these tags do"),
Expand Down
25 changes: 24 additions & 1 deletion diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/chapter2/kdoc/KdocFormatting.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,30 @@ class KdocFormatting(configRules: List<RulesConfig>) : DiktatRule(
KDOC_NO_EMPTY_TAGS, KDOC_NO_NEWLINES_BETWEEN_BASIC_TAGS, KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS,
KDOC_WRONG_SPACES_AFTER_TAG, KDOC_WRONG_TAGS_ORDER),
) {
private val basicTagsList = listOf(KDocKnownTag.PARAM, KDocKnownTag.RETURN, KDocKnownTag.THROWS)
/**
* The reasoning behind the tag ordering:
*
* 1. `@receiver` documents `this` instance which is the 1st function call
* parameter (ordered before `@param`).
* 1. `@param` followed by `@return`, then followed by `@throws` or
* `@exception` is the conventional order inherited from _JavaDoc_.
* 1. `@param` tags can also be used to document generic type parameters.
* 1. `@property` tags are placed after `@param` tags in the official
* [example](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax). Looking at the
* [code](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/src/kotlin/util/Tuples.kt#L22),
* this is also the style _JetBrains_ use themselves.
* 1. looking at the examples, `@constructor` tags are placed last in
* constructor descriptions.
*/
private val basicTagsList = listOf(
KDocKnownTag.RECEIVER,
KDocKnownTag.PARAM,
KDocKnownTag.PROPERTY,
KDocKnownTag.RETURN,
KDocKnownTag.THROWS,
KDocKnownTag.EXCEPTION,
KDocKnownTag.CONSTRUCTOR,
)
private val specialTagNames = setOf("implSpec", "implNote", "apiNote")
private var versionRegex: Regex? = null

Expand Down
2 changes: 1 addition & 1 deletion info/available-rules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
| 2 | 2.1.2 | KDOC_WITHOUT_THROWS_TAG | Check: warns if the accessible method has the throw keyword and it is not documented in KDoc.<br>Fix: if the accessible method has no KDoc, KDoc template is added. | yes | no | Should also make separate fix, even if there is already some Kdoc in place. |
| 2 | 2.1.3 | KDOC_EMPTY_KDOC | Check: warns if the KDoc is empty.<br>Fix: no | no | no | |
| 2 | 2.1.3 | KDOC_WRONG_SPACES_AFTER_TAG | Check: warns if there is more than one space after the KDoc tag.<br>Fix: removes redundant spaces. | yes | no | |
| 2 | 2.1.3 | KDOC_WRONG_TAGS_ORDER | Check: warns if the basic KDoc tags are not ordered properly.<br>Fix: reorders tags (`@param`, `@return`, `@throws`). | yes | no | Ensure basic tags are at the end of KDoc. |
| 2 | 2.1.3 | KDOC_WRONG_TAGS_ORDER | Check: warns if the basic KDoc tags are not ordered properly.<br>Fix: reorders tags (`@receiver`, `@param`, `@property`, `@return`, `@throws` or `@exception`, `@constructor`). | yes | no | Ensure basic tags are at the end of KDoc. |
| 2 | 2.1.3 | KDOC_NEWLINES_BEFORE_BASIC_TAGS | Check: warns if the block of tags (@param, @return, @throws) is not separated from the previous part of KDoc by exactly one empty line.<br>Fix: adds an empty line or removes a redundant one. | yes | no | |
| 2 | 2.1.3 | KDOC_NO_NEWLINES_BETWEEN_BASIC_TAGS | Check: if there is a newline of an empty KDoc line (with a leading asterisk) between `@param`, `@return`, `@throws` tags.<br>Fix: removes the line. | yes | no | |
| 2 | 2.1.3 | KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS | Check: warns if special tags `@apiNote`, `@implNote`, `@implSpec` don't have exactly one empty line after.<br>Fix: removes redundant lines or adds one. | yes | no | Handle empty lines without a leading asterisk. |
Expand Down

0 comments on commit 054894e

Please sign in to comment.