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

[benjamin-kirkbride]

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!

[weibullguy]

docformatter doesn't know how to handle various directives at the moment. It's the next "big thing" I plan to work on. See #58, #60, #68, and #78.

[glenn-jocher]

+1, docformatter is wrapping summaries nicely for me but not descriptions (i.e. the paragraph under the summary):

docformatter \
--wrap-summaries 120 \
--wrap-descriptions 120 \
--in-place \
--pre-summary-newline \
--close-quotes-on-newline \
--recursive \
.

This second line should be reformatted into a small paragraph but is not:

"""
Initializes a new model and infers the task type from the model definitions.

This method creates a new model instance based on the provided configuration file. It loads the model configuration, infers the task type if not specified, and initializes the model using the appropriate class from the task map.

Parameters:
    cfg (str): Path to the model configuration file in YAML format.
    task (str | None): The specific task for the model. If None, it will be inferred from the config.
    model (torch.nn.Module | None): A custom model instance. If provided, it will be used instead of creating a new one.
    verbose (bool): If True, displays model information during loading.

Raises:
    ValueError: If the configuration file is invalid or the task cannot be inferred.
    ImportError: If the required dependencies for the specified task are not installed.

Examples:
    >>> model = Model()
    >>> model._new('yolov8n.yaml', task='detect', verbose=True)
"""

[btjanaka]

I made a super sketchy script that can wrap argument lists here! https://github.com/btjanaka/wrap-docstrings It's pretty limited in that it assumes your docstrings are already google style and there are probably edge cases I didn't account for, but it worked on the code I was using. See the README for some examples of what it can do.

[akul-ameya]

I have been using a solution that gets around this and I have just raised a PR (#381) incorporating that solution, so it can hopefully address it appropriately. I request someone to please review and approve it.
#324 already restores wrapping of the prose before Args: / Returns:, but it leaves those sections unchanged. The new PR wraps each Args/Returns entry as its own unit, keeps the Google structure, and is idempotent.