Rule Request: Require Docstrings

[grantneufeld]

New Issue Checklist

• Updated SwiftLint to the latest version
• I searched for existing GitHub issues

New rule request

require-docstrings (e.g., /// Documentation comment) before functions, classes/enums/structs, protocols, and class/enum/struct variables.

1. Why should this rule be added?

Enforce inclusion of documenting comments.

2. Provide several examples of what would and wouldn't trigger violations.

Invalid:

prototype MyPrototype {}
class MyClass {
  var myVar: Int
  let myConst = "a constant"
  func myFunc() {}
}
struct MyStruct {}
enum MyEnum {
  case myCase
}

Valid:

/// This prototype…
prototype MyPrototype {}
/// A class to…
class MyClass {
  /// Tracks…
  var myVar: Int
  /// The text for…
  let myConst = "a constant"
  /// Do…
  func myFunc() {
    var ignore: Int // no need to document inside a function
  }
}
/// A struct to…
struct MyStruct {}
/// An enum to…
enum MyEnum {
  case myCase
}

3. Should the rule be configurable, if so what parameters should be configurable?

The rule should be configurable:

• access-levels (members of public, internal, fileprivate, private); default; public & internal.
• entity-types [class,function,prototype,variable]; default: all.

4. Should the rule be opt-in or enabled by default? Why?

Opt-in. Because lots of folks prefer not to include documentation comments.

[marcelofabri]

Isn't this the same as https://realm.github.io/SwiftLint/missing_docs.html?

[grantneufeld]

Isn't this the same as https://realm.github.io/SwiftLint/missing_docs.html?

Oh, somewhat.

Turns out that I do have missing_docs active in my .swiftlint.yml file (along with various other opt_in_rules: that are working), but it is failing to generate warnings on my code that is missing docs.

Part of the problem is that missing_docs only checks public code for missing docs, but as I suggested above, I also need it for other access-levels (internal, etc.).

After some experimentation, I’ve found that missing_docs also ignores any cases where inheritance or a protocol is applied to a class/enum/struct. public struct Example {} gets a warning, but public struct Example: View {} does not. It seems that that, and the public requirement, are why I wasn’t seeing any warnings.

So, it seems that this issue is really 3 somewhat separate things:

• Bug report for missing_docs excluding enums/classes/structs that use inheritance or protocols.
• Feature request for options on missing_docs to include more access levels than just public.
• Feature request for options on missing_docs to constrain which entities are checked for missing docs (class, enum, struct, prototype, function, variable, let constants).

[stale]

This issue has been automatically marked as stale because it has not had any recent activity. Please comment to prevent this issue from being closed. Thank you for your contributions!