PyCQA / PyCQA/docformatter

Wrapping doesn't work at all when there is an argument list?

Open
#174 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C: stakeholder question
Dominant language
Python
Stars
598
Forks
93
PR merge metrics
No merged PRs in 30d

Description

I may be ignorant or missing something. Here are some examples:

    """Split audio at silences to keep under the size limit.

    It's important to split near the middle of a silent section to prevent splitting on a spoken word and causing
    issues with transcription and diarization.

    Args:
        silent_sections: list of silent sections in ms.
        duration: total length of audio in ms
        audio_size: total size of audio file in bytes
        max_file_size: maximum file size that may exist after splits

    Returns:
        List of points in ms to use to split the audio file into chunks.
    """

Running docformatter on the above does nothing, unless I specify --force-wrap which does what I want for the long line, but botches the argument list:

    """Split audio at silences to keep under the size limit.

    It's important to split near the middle of a silent section to
    prevent splitting on a spoken word and causing issues with
    transcription and diarization.

    Args:     silent_sections: list of silent sections in ms.
    duration: total length of audio in ms     audio_size: total size of
    audio file in bytes     max_file_size: maximum file size that may
    exist after splits

    Returns:     List of points in ms to use to split the audio file
    into chunks.
    """

Compare to what happens if I remove the lists, and also remove --force-wrap:

    """Split audio at silences to keep under the size limit.

    It's important to split near the middle of a silent section to
    prevent splitting on a spoken word and causing issues with
    transcription and diarization.
    """

Is wrapping all or nothing; if there are lists no lines get wrapped? Or are my arg/returns lists malformed? Any insight is appreciated!

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running docformatter on the supplied docstring examples with and without --force-wrap, comparing behavior when Args and Returns entries are present. Trace the argument-list and wrapping entry points, then add a regression test showing that prose wraps while argument and return entries remain correctly separated and formatted.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.