MAINT: Document D421 property-docstring noun-phrase convention (microsoft#2102)

Co-authored-by: biefan <70761325+biefan@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.github/instructions/style-guide.instructions.md

@@ -481,10 +481,19 @@ async def temporary_config(self, **kwargs):
 ### Property Decorators
 - Use @property for simple computed attributes
 - Use explicit getter/setter methods for complex logic
+- Property docstrings must be **noun phrases** describing the value (e.g.
+  `"""The display name."""`), not verb phrases (e.g. `"""Return the display
+  name."""`). This is enforced by Ruff `D421` (property-docstring-starts-with-verb).
 
 ```python
 # CORRECT
 @property
+def is_complete(self) -> bool:
+    """Whether the attack is complete."""
+    return self._status == AttackStatus.COMPLETE
+
+# INCORRECT - verb-phrase docstring, flagged by Ruff D421
+@property
 def is_complete(self) -> bool:
     """Check if the attack is complete."""
     return self._status == AttackStatus.COMPLETE

pyproject.toml

@@ -324,6 +324,9 @@ select = [
     "B",  # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
     "C4",  # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
     "CPY001",  # missing-copyright-notice
+    # "D" + preview=true enables D421 (property-docstring-starts-with-verb):
+    # property docstrings must be noun phrases ("""The display name."""), not
+    # verb phrases ("""Return the display name."""). Keep "D" selected, not ignored.
     "D",  # https://docs.astral.sh/ruff/rules/#pydocstyle-d
     "DOC",  # https://docs.astral.sh/ruff/rules/#pydoclint-doc
     "DTZ",  # https://docs.astral.sh/ruff/rules/#flake8-datetimez-dtz