restore comments automatically stripped by [#250]

pyproject.toml

@@ -113,61 +113,66 @@ src = [
 
 [tool.ruff.lint]
 extend-select = [
-    "F",
-    "W",
-    "E",
-    "I",
-    "D",
-    "UP",
-    "YTT",
-    "ANN",
-    "S",
-    "BLE",
-    "B",
-    "A",
-    "C4",
-    "T10",
-    "EM",
-    "FA",
-    "ISC",
-    "ICN",
-    "G",
-    "INP",
-    "PIE",
-    "PT",
-    "Q",
-    "RSE",
-    "RET",
-    "SLF",
-    "SLOT",
-    "SIM",
-    "TID",
-    "TCH",
-    "INT",
-    "PTH",
-    "PGH",
-    "PL",
-    "TRY",
-    "FLY",
-    "NPY",
-    "PERF",
+    "F",      # Pyflakes (part of default flake8)
+    "W", "E", # pycodestyle (part of default flake8)
+    "I",      # isort (import sorting)
+    # "N",      # pep8-naming
+    "D",      # pydocstyle (docstring style guide)
+    "UP",     # pyupgrade (upgrade code to modern python)
+    "YTT",    # flake8-2020 (system version info)
+    "ANN",    # flake8-annotations (best practices for type annotations)
+    "S",      # flake8-bandit (security checks)
+    "BLE",    # flake8-blind-except (prevent blind except statements)
+    "B",      # flake8-bugbear (prevent common gotcha bugs)
+    "A",      # flake8-builtins (prevent shadowing of builtins)
+    "C4",     # flake8-comprehensions (best practices for comprehensions)
+    "T10",    # flake8-debugger (prevent debugger statements in code)
+    "EM",     # flake8-errormessages (best practices for error messages)
+    "FA",     # flake8-future-annotations (correct usage future annotations)
+    "ISC",    # flake8-implicit-str-concat (prevent implicit string concat)
+    "ICN",    # flake8-import-conventions (enforce import conventions)
+    "G",      # flake8-logging-format (best practices for logging)
+    "INP",    # flake8-no-pep420 (prevent use of PEP420, i.e. implicit name spaces)
+    "PIE",    # flake8-pie (misc suggested improvement linting)
+    # "T20",    # flake8-print (prevent print statements in code)
+    "PT",     # flake8-pytest-style (best practices for pytest)
+    "Q",      # flake8-quotes (best practices for quotes)
+    "RSE",    # flake8-raise (best practices for raising exceptions)
+    "RET",    # flake8-return (best practices for return statements)
+    "SLF",    # flake8-self (prevent private member access)
+    "SLOT",   # flake8-slots (require __slots__ for immutable classes)
+    "SIM",    # flake8-simplify (suggest simplifications to code where possible)
+    "TID",    # flake8-tidy-imports (prevent banned api and best import practices)
+    "TCH",    # flake8-type-checking (move type checking imports into type checking blocks)
+    "INT",    # flake8-gettext (when to use printf style strings)
+    # "ARG",    # flake8-unused-arguments (prevent unused arguments)
+    "PTH",    # flake8-use-pathlib (prefer pathlib over os.path)
+    # "ERA",    # eradicate (remove commented out code)
+    "PGH",    # pygrep (simple grep checks)
+    "PL",     # pylint (general linting, flake8 alternative)
+    "TRY",    # tryceratops (linting for try/except blocks)
+    "FLY",    # flynt (f-string conversion where possible)
+    "NPY",    # NumPy-specific checks (recommendations from NumPy)
+    "PERF",   # Perflint (performance linting)
     "LOG",
-    "RUF",
+    "RUF",    # ruff specific checks
 ]
 ignore = [
-    "ISC001",
-    "PLR0912",
-    "PLR0913",
-    "PLR0915",
-    "PLR2004",
-    "D100",
-    "D101",
-    "D102",
-    "D103",
-    "D104",
-    "D205",
-    "D401",
-    "D404",
+    "ISC001", # interferes with formatter
+    "PLR0912", # Too many branches
+    "PLR0913", # Too many arguments
+    "PLR0915", # Too many statements
+    "PLR2004", # Magic value used in comparison
+
+    # Pydocstyle (to fix over time
+    "D100", # Undocumented public module
+    "D101", # Undocumented public class
+    "D102", # Undocumented public method
+    "D103", # Undocumented public function
+    "D104", # Undocumented public package
+    "D205", # 1 blank line required between summary line and description
+    "D401", # First line of docstring should be in imperative mood
+    "D404", # First word of docstring should not be This
 ]
 exclude = [
     "docs",
@@ -187,7 +192,7 @@ exclude = [
 convention = "numpy"
 
 [tool.ruff.lint.flake8-annotations]
-ignore-fully-untyped = true
+ignore-fully-untyped = true  # Turn of annotation checking for fully untyped code
 
 [tool.cython-lint]
 max-line-length = 110
@@ -202,10 +207,10 @@ skip = "*.pdf,*.fits,*.asdf,.tox,build,./tags,.git,docs/_build"
 
 [tool.repo-review]
 ignore = [
-    "GH200",
-    "PC140",
-    "PC901",
-    "MY100",
+    "GH200",  # Use dependabot
+    "PC140",  # add MyPy to pre-commit
+    "PC901",  # custom pre-comit.ci message
+    "MY100",  # Use MyPy
 ]
 
 [tool.cibuildwheel.macos]