CLN: re-wrap docstrings in pandas\compat\numpy\function.py
State: closed


Labels:
name: Clean

Comments:
Is there a preference towards semantic linefeeds?
Described here: https://rhodesmill.org/brandon/2012/one-sentence-per-line/

Not that I object against the changes, but probably it would be beneficial to embrace this approach.
Maybe not so dramatically, like placing newline after each comma, but at least keep one logical thought at a line.
> Is there a preference towards semantic linefeeds?

I think ALT-Q (or whatever your editor uses) is easier and makes semantic linefeeds redundant
> 
> 
> > Is there a preference towards semantic linefeeds?
> 
> I think ALT-Q (or whatever your editor uses) is easier and makes semantic linefeeds redundant

It is easy to re-format, but this creates large diffs, even if one word was changed.
The point of semantic linefeeds is to reduce possible diffs to a minimum.
> The point of semantic linefeeds is to reduce possible diffs to a minimum.

I thought it was to primarily to make files easier to change.

> It is easy to re-format, but this creates large diffs, even if one word was changed.

not so much of an issue imo with the two-tone diff helping to identify the changes.

I've looked through a few standard library modules, double checked PEP 257 and the google python style guide. Can you link some Python packages that use semantic linefeeds.

> but at least keep one logical thought at a line.

can't argue with that. if logical thoughts need to be seperated, can insert a blank line and then wrapping tools will respect that.
> 
> 
> > The point of semantic linefeeds is to reduce possible diffs to a minimum.
> 
> I thought it was to primarily to make files easier to change.
> 
> > It is easy to re-format, but this creates large diffs, even if one word was changed.
> 
> not so much of an issue imo with the two-tone diff helping to identify the changes.
> 
> I've looked through a few standard library modules, double checked PEP 257 and the google python style guide. Can you link some Python packages that use semantic linefeeds.

Unfortunately, I do not know if there are open source projects using this approach.
I personally use it for technical writing and documentation.
I noticed that the readability improved
as well as ability to track changes.
The number of conflicts
when working on the documentation in a team 
would also dramatically reduce.

I think that this technique is not used widely because of the modern tools for wrapping paragraphs. Moreover, it is difficult to enforce its use. Just a food for thought.
https://sembr.org/


> I think that this technique is not used widely because of the modern tools for wrapping paragraphs. Moreover, it is difficult to enforce its use. Just a food for thought.
> https://sembr.org/

from the article, it could make sense for markup languages where the line break does not affect the rendered output, but for docstrings, the line breaks are releavant, so 'A semantic line break must not alter the final rendered output of the document.' in the specification is violated.

```
>>> import pandas.compat.numpy.function as f
>>> help(f)
Help on module pandas.compat.numpy.function in pandas.compat.numpy:

NAME
    pandas.compat.numpy.function

DESCRIPTION
    For compatibility with numpy libraries, pandas functions or
    methods have to accept '*args' and '**kwargs' parameters to
    accommodate numpy arguments that are not actually used or
    respected in the pandas implementation.

    To ensure that users do not abuse these parameters, validation
    is performed in 'validators.py' to make sure that any extra
    parameters passed correspond ONLY to those in the numpy signature.
    Part of that validation includes whether or not the user attempted
    to pass in non-default values for these extraneous parameters. As we
    want to discourage users from relying on these parameters when calling
    the pandas implementation, we want them only to pass in the default values
    for these parameters.

    This module provides a set of commonly used default arguments for functions
    and methods that are spread throughout the codebase. This module will make it
    easier to adjust to future upstream changes in the analogous numpy signatures.

```
Right, agree on the docstrings. I forgot that we consider help output in the shell.
Could be worth considering for rst though.
yes, it's unfortunate that sphinx also supports line breaks as whitespace. I think we have some public docstrings that look fine in code but don't render so well in the online docs.

but indeed for the rst files, maybe worthwhile considering.