GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Unclear why fun.py (and others?) shouldn't have a module docstring · Issue #1733 · gitpython-developers/GitPython

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

New issue
Copy link
New issue
Copy link
Closed
#1735
Closed
Unclear why fun.py (and others?) shouldn't have a module docstring#1733
#1735
Copy link
Labels
acknowledgedhelp wanted

Description

@EliahKagan
EliahKagan
opened on Nov 4, 2023
Issue body actions

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

GitPython/git/index/fun.py

Lines 1 to 2 in d5fc6e5

# 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:

GitPython/git/index/fun.py

Lines 1 to 3 in add46d9

# 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).

Activity

  1. Byron commented on Nov 6, 2023

    @Byron
    Byron
    on Nov 6, 2023
    Member
    More actions

    That's an interesting find and I don't have an answer as to why that was necessary then. Ideally, that would have been in the commit message that introduced the comment, but here we are.
    My guess is that it's alright to change it back and see what happens, I'd expect it to work as well.

    Reacted by Eliah Kagan
  2. Byron
    added
    acknowledged
    help wanted
    on Nov 6, 2023
  3. EliahKagan
    added a commit that references this issue on Nov 6, 2023

    Revise and restore some module docstrings

    aed3b59

  4. EliahKagan commented on Nov 6, 2023

    @EliahKagan
    EliahKagan
    on Nov 6, 2023
    MemberAuthor
    More actions

    Sounds good. I've done this in #1735, which also revises some already-present module docstrings.

  5. Byron
    closed this as completedin #1735on Nov 6, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    acknowledgedhelp wanted

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions
      You are visitor 01402503 — GeezerVison does not store the pages you look up.
      Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.