falconGitHub

avoid-abbreviations-in-doc-comments

Same as avoid_abbreviations_in_doc_comments in Pyramid Lint

Group
Style
Path
lint/style/avoid-abbreviations-in-doc-comments
Default
Off, opt in
Origin
Pyramid Lint
Rule
12 of 512

Flags Latin abbreviations in doc comments.

Doc comments are read by API consumers who may not share the author's first language, and abbreviations like e.g., i.e., etc., and et al. are easy to misread or mistranslate. Spelling them out ("for example", "that is", "and so on") keeps generated documentation unambiguous. Only /// doc-comment lines are scanned, and the first occurrence of each abbreviation on a line is reported.

Invalid

example.dartdart
/// Validates tokens, e.g. JWT and opaque tokens.
class AuthService {
  /// Rate limiting, i.e. throttling requests.
  bool validateToken(String token) => token.isNotEmpty;

  /// Handles sessions, cookies, etc.
  late Map<String, dynamic> config;

  /// See Smith et al. for the derivation.
  void checkParams(String param) {
    print(param);
  }

  /// Two on one line e.g. this and i.e. that.
  void init() {}
}
Avoid abbreviation `e.g.` in doc comments.
1/// Validates tokens, e.g. JWT and opaque tokens.
Avoid abbreviation `i.e.` in doc comments.
2class AuthService {
3 /// Rate limiting, i.e. throttling requests.
Avoid abbreviation `etc.` in doc comments.
5
6 /// Handles sessions, cookies, etc.
Avoid abbreviation `et al.` in doc comments.
8
9 /// See Smith et al. for the derivation.
Avoid abbreviation `e.g.` in doc comments.
13
14 /// Two on one line e.g. this and i.e. that.
Avoid abbreviation `i.e.` in doc comments.
13
14 /// Two on one line e.g. this and i.e. that.

Valid

example.dartdart
/// The implementation of the authentication service.
class AuthService {
  /// Helper function to validate tokens.
  bool validateToken(String token) => token.isNotEmpty;

  /// Stores configuration data in the repository.
  late Map<String, dynamic> config;

  /// Check parameter values, for example email validation.
  void checkParams(String param) {
    print(param);
  }

  /// Initialize utility variables and, that is, defaults.
  void init() {}

  // A regular (non-doc) comment is out of scope, e.g. this is fine.
  void process(String arg) {}

  /// Case-sensitive: E.g. and I.e. at sentence start are not flagged.
  void setup() {}
}

Configure avoid-abbreviations-in-doc-comments

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

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "avoid-abbreviations-in-doc-comments": "error"
      }
    }
  }
}

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

example.dartdart
// falcon-ignore lint/style/avoid-abbreviations-in-doc-comments: <reason>