Skip to content

Unclear why fun.py (and others?) shouldn't have a module docstring #1733

Closed
@EliahKagan

Description

@EliahKagan

While working on #1725 I noticed the git.index.fun module has this comment at the top:

# Standalone functions to accompany the index implementation and make it more versatile.
# NOTE: Autodoc hates it if this is a docstring.

Actually, that exact comment is due to my revision in that PR, but it's revised from:

# Contains standalone functions to accompany the index implementation and make it
# more versatile
# NOTE: Autodoc hates it if this is a docstring

This was introduced in 9ccd777, at which time an existing module docstring was converted to a comment instead. Various other module docstrings were also converted to comments. But some modules today do have docstrings. Running make -C doc html seems to work fine; I ran it a number of times on Ubuntu and Windows while working on that PR and since.

I didn't want to assume it was okay to turn that back into a docstring. But either it (and any other top of module comments) should be turned into docstrings, or the reason they should not be should be made clearer (and any module docstrings causing problems fixed or converted back to comments).

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions