Ignore missing docstring on main function (D103)

[jn64]

This was an unresolved feature request in pydocstyle regarding undocumented-public-function (D103).

If a public module/script has a top-level docstring, it's probably redundant to document the main function.

Like the original reporter, I don't want to ignore D103, or add # noqa: D103 to every def main(): of every file.

I guess ruff wouldn't change a rule inherited from another tool, but is it possible to have a variant of this rule that excludes main functions? So I could ignore D103 and select (for example) D103A.

[ntBre]

Thanks for opening the discussion! I can definitely see the argument here, but I'm not sure if we'd want to exclude "main" specifically or expose some kind of configuration knob here. I don't think we'd want a separate rule entirely. To me, this seems like a good use case for noqa, or per-file-ignores if all of the scripts are in a single directory. Another option that I've used in the past is just to call the main function _main instead of main.

[jn64]

Sorry, I wrote too informally and failed to communicate the intent clearly.

D103 warns about missing docstring on all public functions.

I propose a (variant/configuration of) D103 that:

• warns about missing docstring on all public functions (including main)
• but doesn't warn about main if there is a docstring at the top of the file.

Ignoring D103 entirely at file/folder/project level does not have the same effect.

---

main is merely a convention in Python, so I understand not wanting to special case it (frankly speaking, I support this view).

In which case, the alternative proposal (also unresolved in pydocstyle) is to have a configuration option for D103 to ignore a given list of functions. The same or similar option might also apply to D102 undocumented-public-method.

# EXAMPLE
[tool.ruff.lint.pydocstyle]
# (D103) Ignore missing docstrings on given functions
ignore-missing-docstrings-on-functions = [
    "main",
]
# (D102) Ignore missing docstrings on given methods
ignore-missing-docstrings-on-methods = [
    "__init__",
]

[ntBre]

Oh I see what you mean, I overlooked the top-level docstring part. I think a configuration option could be a reasonable solution, but I'll be curious to see what @MichaReiser thinks when he's back from PTO.

[jn64]

Oops, turns out this was already requested at least twice before:

• pydocstyle: Ignore matching functions #7401
• Add exclusions for D103 #10016 which, despite the name, covers D100 to D104

[ntBre]

Thanks for following up and finding the issues! I hadn't found those.