Add documentation for mccabe, isort, and flake8-annotations (#2691)

docs/rules/commented-out-code.md

@@ -13,4 +13,5 @@ It should be removed.
 
 ### Example
 ```python
+# print('foo')
 ```

docs/rules/dynamically-typed-expression.md

@@ -0,0 +1,23 @@
+# dynamically-typed-expression (ANN401)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that an expression is annotated with a more specific type than `Any`.
+
+### Why is this bad?
+`Any` is a type that can be anything, and it is the default type for
+unannotated expressions. It is better to be explicit about the type of an
+expression, and to use `Any` only when it is really needed.
+
+### Example
+```python
+def foo(x: Any):
+    ...
+```
+
+Use instead:
+```python
+def foo(x: int):
+    ...
+```

docs/rules/function-is-too-complex.md

@@ -0,0 +1,41 @@
+# function-is-too-complex (C901)
+
+Derived from the **mccabe** linter.
+
+### What it does
+Checks for functions with a high `McCabe` complexity.
+
+The `McCabe` complexity of a function is a measure of the complexity of the
+control flow graph of the function. It is calculated by adding one to the
+number of decision points in the function. A decision point is a place in
+the code where the program has a choice of two or more paths to follow.
+
+### Why is this bad?
+Functions with a high complexity are hard to understand and maintain.
+
+### Example
+```python
+def foo(a, b, c):
+    if a:
+        if b:
+            if c:
+                return 1
+            else:
+                return 2
+        else:
+            return 3
+    else:
+        return 4
+```
+
+Use instead:
+```python
+def foo(a, b, c):
+    if not a:
+        return 4
+    if not b:
+        return 3
+    if not c:
+        return 2
+    return 1
+```

docs/rules/missing-required-import.md

@@ -0,0 +1,26 @@
+# missing-required-import (I002)
+
+Derived from the **isort** linter.
+
+Autofix is always available.
+
+### What it does
+Adds any required imports, as specified by the user, to the top of the file.
+
+### Why is this bad?
+In some projects, certain imports are required to be present in all files. For
+example, some projects assume that `from __future__ import annotations` is enabled,
+and thus require that import to be present in all files. Omitting a "required" import
+(as specified by the user) can cause errors or unexpected behavior.
+
+### Example
+```python
+import typing
+```
+
+Use instead:
+```python
+from __future__ import annotations
+
+import typing
+```

docs/rules/missing-return-type-class-method.md

@@ -0,0 +1,27 @@
+# missing-return-type-class-method (ANN206)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that class methods have return type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the return types of functions. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any returned values, and the types expected by callers, match expectation.
+
+### Example
+```python
+class Foo:
+    @classmethod
+    def bar(cls):
+        return 1
+```
+
+Use instead:
+```python
+class Foo:
+    @classmethod
+    def bar(cls) -> int:
+        return 1
+```

docs/rules/missing-return-type-private-function.md

@@ -0,0 +1,23 @@
+# missing-return-type-private-function (ANN202)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that private functions and methods have return type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the return types of functions. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any returned values, and the types expected by callers, match expectation.
+
+### Example
+```python
+def _add(a, b):
+    return a + b
+```
+
+Use instead:
+```python
+def _add(a: int, b: int) -> int:
+    return a + b
+```

docs/rules/missing-return-type-public-function.md

@@ -0,0 +1,23 @@
+# missing-return-type-public-function (ANN201)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that public functions and methods have return type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the return types of functions. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any returned values, and the types expected by callers, match expectation.
+
+### Example
+```python
+def add(a, b):
+    return a + b
+```
+
+Use instead:
+```python
+def add(a: int, b: int) -> int:
+    return a + b
+```

docs/rules/missing-return-type-special-method.md

@@ -0,0 +1,38 @@
+# missing-return-type-special-method (ANN204)
+
+Derived from the **flake8-annotations** linter.
+
+Autofix is always available.
+
+### What it does
+Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
+return type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the return types of functions. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any returned values, and the types expected by callers, match expectation.
+
+Note that type checkers often allow you to omit the return type annotation for
+`__init__` methods, as long as at least one argument has a type annotation. To
+opt-in to this behavior, use the `mypy-init-return` setting in your `pyproject.toml`
+or `ruff.toml` file:
+
+```toml
+[tool.ruff.flake8-annotations]
+mypy-init-return = true
+```
+
+### Example
+```python
+class Foo:
+    def __init__(self, x: int):
+        self.x = x
+```
+
+Use instead:
+```python
+class Foo:
+    def __init__(self, x: int) -> None:
+        self.x = x
+```

docs/rules/missing-return-type-static-method.md

@@ -0,0 +1,27 @@
+# missing-return-type-static-method (ANN205)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that static methods have return type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the return types of functions. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any returned values, and the types expected by callers, match expectation.
+
+### Example
+```python
+class Foo:
+    @staticmethod
+    def bar():
+        return 1
+```
+
+Use instead:
+```python
+class Foo:
+    @staticmethod
+    def bar() -> int:
+        return 1
+```

docs/rules/missing-type-args.md

@@ -0,0 +1,23 @@
+# missing-type-args (ANN002)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that function `*args` arguments have type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the types of function arguments. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any provided arguments match expectation.
+
+### Example
+```python
+def foo(*args):
+    ...
+```
+
+Use instead:
+```python
+def foo(*args: int):
+    ...
+```

docs/rules/missing-type-cls.md

@@ -0,0 +1,30 @@
+# missing-type-cls (ANN102)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that class method `cls` arguments have type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the types of function arguments. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any provided arguments match expectation.
+
+Note that many type checkers will infer the type of `cls` automatically, so this
+annotation is not strictly necessary.
+
+### Example
+```python
+class Foo:
+    @classmethod
+    def bar(cls):
+        ...
+```
+
+Use instead:
+```python
+class Foo:
+    @classmethod
+    def bar(cls: Type["Foo"]):
+        ...
+```

docs/rules/missing-type-function-argument.md

@@ -0,0 +1,23 @@
+# missing-type-function-argument (ANN001)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that function arguments have type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the types of function arguments. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any provided arguments match expectation.
+
+### Example
+```python
+def foo(x):
+    ...
+```
+
+Use instead:
+```python
+def foo(x: int):
+    ...
+```

docs/rules/missing-type-kwargs.md

@@ -0,0 +1,23 @@
+# missing-type-kwargs (ANN003)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that function `**kwargs` arguments have type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the types of function arguments. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any provided arguments match expectation.
+
+### Example
+```python
+def foo(**kwargs):
+    ...
+```
+
+Use instead:
+```python
+def foo(**kwargs: int):
+    ...
+```

docs/rules/missing-type-self.md

@@ -0,0 +1,28 @@
+# missing-type-self (ANN101)
+
+Derived from the **flake8-annotations** linter.
+
+### What it does
+Checks that instance method `self` arguments have type annotations.
+
+### Why is this bad?
+Type annotations are a good way to document the types of function arguments. They also
+help catch bugs, when used alongside a type checker, by ensuring that the types of
+any provided arguments match expectation.
+
+Note that many type checkers will infer the type of `self` automatically, so this
+annotation is not strictly necessary.
+
+### Example
+```python
+class Foo:
+    def bar(self):
+        ...
+```
+
+Use instead:
+```python
+class Foo:
+    def bar(self: "Foo"):
+        ...
+```

docs/rules/unsorted-imports.md

@@ -0,0 +1,24 @@
+# unsorted-imports (I001)
+
+Derived from the **isort** linter.
+
+Autofix is always available.
+
+### What it does
+De-duplicates, groups, and sorts imports based on the provided `isort` settings.
+
+### Why is this bad?
+Consistency is good. Use a common convention for imports to make your code
+more readable and idiomatic.
+
+### Example
+```python
+import pandas
+import numpy as np
+```
+
+Use instead:
+```python
+import numpy as np
+import pandas
+```