Skip to content

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

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

Copy link
Copy link
Closed
@EliahKagan

Description

@EliahKagan
Issue body actions

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

      Morty Proxy This is a proxified and sanitized view of the page, visit original site.