falcon

Rules / Style / slash-for-doc-comments

slash-for-doc-comments

lint/style/slash-for-doc-comments
recommended
Same as slash_for_doc_comments · Dart lints

Flags /** ... */ block documentation comments in favor of the /// form.

Dart supports two doc-comment syntaxes, but the community style guide standardizes on the end-of-line /// form; the /** ... */ block form is discouraged. Using a single style keeps doc comments consistent and easy to scan. Detection scans the raw source with a small state machine so /** sequences inside strings, line comments, or ordinary block comments are ignored, and the empty /**/ comment is not mistaken for a doc comment.

Invalid

example.dartdart
/** A documented class. */
class A {}

/** Documents the second class. */
class B {}

/** Documents the third class. */
class C {}

/** Documents the fourth class. */
class D {}

/** Documents the fifth class. */
class E {}
Use the end-of-line form ('///') for doc comments.
1/** A documented class. */
Use the end-of-line form ('///') for doc comments.
3
4/** Documents the second class. */
Use the end-of-line form ('///') for doc comments.
6
7/** Documents the third class. */
Use the end-of-line form ('///') for doc comments.
9
10/** Documents the fourth class. */
Use the end-of-line form ('///') for doc comments.
12
13/** Documents the fifth class. */

Valid

example.dartdart
/// A documented class using the end-of-line form.
class A {}

/// Documents the second class.
class B {}

/* An ordinary block comment, not a doc comment. */
class C {}

/*
 * A single-star banner block, still not a doc comment.
 */
class D {}

// A plain line comment.
class E {}

How to configure

Set the severity of slash-for-doc-comments in your falcon.json:

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "slash-for-doc-comments": "error"
      }
    }
  }
}

Related