Add WPS484: forbid strings that document nothing

[vyhuholl]

I have made things!

Adds WPS484, the rule from #3808. It flags a string statement placed where it cannot document anything:

some.first = 1
"""Documents nothing, `first` belongs to `some`."""


def some(arg):
    """Function docs."""
    if arg:
        """Neither does this."""
        return arg
    return 0

A string documents something in exactly four places:

• opening a module, class or function body
• after an assignment to a plain name in a module or a class
• after self.some = ... inside a method
• after a type Some = ... alias on python3.12+

The check itself is a single condition, because WPS226 already had to answer this same question in order to skip docstrings:

def _check_doc_string_place(self, node: ast.Expr) -> None:
    if strings.is_doc_string(node) and not strings.is_doc_string_value(
        node.value,
    ):
        self.add_violation(WrongDocStringPlacementViolation(node))

That reuse is the point of the rule, not a shortcut. Both rules now read one definition of a documenting position, so refining it later moves them together instead of letting two copies drift.

The violation sits in best_practices.py next to WPS428, the old "statement has no effect" rule that was retired to ruff's B015/B018 in 1.0.0. Neither of those flags a string, which is how these slip through today.

wemake-python-styleguide itself is clean under the new rule.

Open to review

I picked these three without asking, so say if any is wrong:

• the name, WrongDocStringPlacementViolation
• the code, WPS484
• counting type Some = int docstrings as a valid position, given they're still only a proposal upstream

AI Policy

• I have read and agree to the AI Policy, removed any "Co-Authored-By" lines attributing coding agents, and manually reviewed the final result

Checklist

• I have double checked that there are no unrelated changes in this pull request (old patches, accidental config files, etc)
• I have created at least one test case for the changes I have made
• I have updated the documentation for the changes I have made
• I have added my changes to the CHANGELOG.md

Related issues

Closes #3808

🙏 Please, if you or your company is finding wemake-python-styleguide valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/wemake-python-styleguide. As a thank you, your profile/company logo will be added to our main README which receives hundreds of unique visitors per day.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (336341c) to head (663120a).

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #3810   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          374       375    +1     
  Lines        12708     12763   +55     
  Branches       879       880    +1     
=========================================
+ Hits         12708     12763   +55     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sobolevn]

The first correction:

after self.some = ... inside a constructor

Not in every other method

:)

[sobolevn]

👍

[sobolevn]

Thanks!

Last fixes:

• please test dataclass-style attrs explicitly, with and without default values
• there's a common error that people use """Docstring""" before the attribute, not after. we should also explicitly test and report this case

[vyhuholl]

Added tests for dataclass-style attrs and for attribute docstring placement. Both cases already behaved correctly, so no code change was needed.

[sobolevn]

Thanks!