wjones127 commented on pull request #11726: URL: https://github.com/apache/arrow/pull/11726#issuecomment-1010145892
> My stance is that docstrings should be meant as human readable text, and I think only a minority of python users is familiar with typing syntax. Well that's sort of the problem here; the numpydoc's having a hard time reading the human-readable text 😉 That being said, I think it's totally fine in the case of `list of`; that's something this was explicitly designed for according to this test: https://github.com/numpy/numpydoc/blob/main/numpydoc/tests/test_xref.py#L44 While `list of` is pretty standard, there are some more deviant descriptions that might need to be changed. For example, the `pandas.Series or pandas.Dataframe depending on type of object`, should probably be changed to just `pandas.Series or pandas.Dataframe`, and then in the return description we should add `Returns series if ___ and DataFrame otherwise`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
