falconGitHub

slash-for-doc-comments

Same as slash_for_doc_comments in Dart lints

Group
Style
Path
lint/style/slash-for-doc-comments
Default
On (recommended)
Origin
Dart lints
Rule
435 of 512
recommended

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 quote/comment state machine, not the Dart lexer, and excludes the empty /**/ comment. It does not fully model raw, multiline or interpolated strings, or nested block comments.

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 {}

Configure slash-for-doc-comments

Set its severity in falcon.json. See the configuration guide.

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

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/slash-for-doc-comments: <reason>
  • sort-child-properties-lastsort_child_properties_lastrecommendedflutter

    Sort Widget-valued child properties last, except before closure arguments.

  • sort-constructors-firstsort_constructors_first

    Flags a constructor declared after a non-constructor member.

  • sort-unnamed-constructors-firstsort_unnamed_constructors_first

    Flags an unnamed constructor declared after a named constructor.

  • tighten-type-of-initializing-formalstighten_type_of_initializing_formals

    Flags a nullable this.x or super.x initializing formal whose constructor asserts x != null.

  • type-annotate-public-apistype_annotate_public_apisrecommended

    Requires type annotations on public declarations.

  • type-init-formalstype_init_formalsrecommended

    Flags a *redundant* type annotation on an initializing formal or super parameter (type-init-formals, adopted from package:lints).

  • unawaited-futuresunawaited_futuresrecommended

    Future results in async bodies must be awaited or marked unawaited.

  • unintended-html-in-doc-commentunintended_html_in_doc_commentrecommended

    Flags angle-bracket text in doc comments that Markdown would render as an HTML tag.