falcon

Rules / Style / avoid-abbreviations-in-doc-comments

avoid-abbreviations-in-doc-comments

lint/style/avoid-abbreviations-in-doc-comments
recommended
Same as avoid_abbreviations_in_doc_comments · Pyramid Lint

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

How to configure

Set the severity of avoid-abbreviations-in-doc-comments in your falcon.json:

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

Related