D417 Argument descriptions only required if there is an "Args" section

[jackdesert]

Expected the code snippet below to show D417. That is, expected it to tell me that the "name" argument does not have a description in the docstring. If I change the word "Parameters" to "Args", then it will raise D417 as desired. Not sure if this is expected behavior, but it has been challenging to figure out.

Version: ruff 0.0.237

Code:

def hello(name):
    """
    Do something.

    Parameters:
        other (str): what to call it

    Returns:
        bool: True if len(name) > 0
    """
    return len(name) > 0

Command:

ruff *.py

Output:

run.py:1:1: D100 Missing docstring in public module
Found 1 error.

pyproject.toml:

[tool.black]
skip-string-normalization = 1

[tool.ruff]
# Enable Pyflakes `E` and `F` codes by default.
select = ["ALL"]

# It appears that a single "Q" ignores all codes that start with Q
# but you could also disable single errors instead of classes of errors
ignore = ["INP001", # implicit-namespace-package
          "ANN",    # type annotations
          "T20",    # flake8-print (warns when there are print statements)

          # One of these is to be disabled..
          # (I prefer disabling D212 (Multi-line docstring summary should start at the first line)
          #  because I like text inside a docstring
          #  to start the line below the three """)
          #"D213", # See https://github.com/charliermarsh/ruff/issues/2281
          "D212", # See https://github.com/charliermarsh/ruff/issues/2281

          # One of these is to be disabled.
          # No strong preference here.
          # One expects a blank line before a class docstring
          #"D203", # See https://github.com/charliermarsh/ruff/issues/2281
          "D211", # See https://github.com/charliermarsh/ruff/issues/2281

]


# Allow autofix for all enabled rules (when `--fix`) is provided.
fixable = ["A", "B", "C", "D", "E", "F"]
unfixable = []

# Exclude a variety of commonly ignored directories.
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
]
per-file-ignores = {}

# Same as Black.
line-length = 88

# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

# Assume Python 3.10.
target-version = "py310"

[tool.ruff.mccabe]
# Unlike Flake8, default to a complexity level of 10.
max-complexity = 10

# This is how you tell Q000 errors to prefer single quotes
[tool.ruff.flake8-quotes]
inline-quotes = "single"

# I like the google docstyle
# See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
# and http://google.github.io/styleguide/pyguide.html
# https://gist.github.com/redlotus/3bc387c2591e3e908c9b63b97b11d24e
# If it complains that you do not have an argument description,
# make sure you have a section called "Args:", not "Arguments" or "Parameters"
[tool.ruff.pydocstyle]
convention = "google"  # Or "numpy", or "pep257"
#convention = "pep257"  # Or "numpy", or "pep257"

[jackdesert]

I kept focusing in on the line with the actual argument instead of the "Parameters" heading.

The most helpful thing for me, being new to both ruff and pydocstyle, would be if it told me that I didn't even have a section called "Args".

But most confusing was when it didn't raise any error at all. So even if it just raised the generic D417 Missing argument description in the docstring: 'name' that would be better than not raising any error at all.

[charliermarsh]

Yeah "Parameters" isn't a respected Google-style heading, so it basically ignores it. I believe pydocstyle has similar behavior. (They probably do warn when you use Parameters, but IMO for the wrong reason. IIRC, if you use Parameters, they infer that you're using a NumPy-style docstring, which can cause other problems in how they validate it. Our configuration is more explicit.)

I think either Args: or Arguments: works in my testing.

One thing we could do to make this clearer is warn when you use a heading that isn't in the list of valid Google section names (assuming you have convention = "google" set, and similarly for NumPy):

[
    "Args",
    "Arguments",
    "Attention",
    "Attributes",
    "Caution",
    "Danger",
    "Error",
    "Example",
    "Examples",
    "Hint",
    "Important",
    "Keyword Args",
    "Keyword Arguments",
    "Methods",
    "Note",
    "Notes",
    "Return",
    "Returns",
    "Raises",
    "References",
    "See Also",
    "Tip",
    "Todo",
    "Warning",
    "Warnings",
    "Warns",
    "Yield",
    "Yields",
]

[jackdesert]

Warning about an incorrect heading would be awesome.

What is the expected behavior if there is no heading at all (when we want to see D417 errors)?

[charliermarsh]

Warning about an incorrect heading would be awesome.

Yeah we could easily do this. It might need to be marked as an explicitly-enabled rule though, and not something that's automatically enabled as part of the D rule set, since it deviates from pydocstyle.

What is the expected behavior if there is no heading at all (when we want to see D417 errors)?

I think if you omit that section, there's no way to enforce that the errors are present. I think that's consistent with pydocstyle unfortunately.

I want to implement darglint (#458) which will be more comprehensive and would handle that, but I can't work on it immediately.

[wyardley]

The most helpful thing for me, being new to both ruff and pydocstyle, would be if it told me that I didn't even have a section called "Args".

Agreed; also, it won't catch misspellings / typos / etc. like if the section is headed Arguments vs Args.

Now that pydocstyle seems to be deprecated in favor of this project, are all the components related to it being maintained directly here?

[adamjstewart]

Encountered this issue too because I was missing an Args: section entirely. I would expect D417 to be raised if none of my params are undocumented, not only when some of my params are undocumented.

[charliermarsh]

This might need to be a new rule, like: you're missing a required section.

[adamjstewart]

I would also be fine with a new rule for this, see #11435 which is related.