jorisvandenbossche commented on pull request #11726: URL: https://github.com/apache/arrow/pull/11726#issuecomment-1010158811
> Well that's sort of the problem here; the numpydoc's having a hard time reading the human-readable text wink But I didn't mean any random "free-form" text :). But yes, I agree with you that most cases that don't fall into this "type1 or type2" or "type1 of type2" cases, should probably be rewritten anyway, and moved into the description field. That's also the reason why I put the `"values coercible to arrays"` above with a TODO comment. That is needed in the ignore list for formatting the _current_ docstrings as is, but I think we should rather use a fixed set of terms like "array-like" for this, and if needed have a more free-form explanation of what that means in the parameter description on the next line. So fully agreed with: > 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`. Note that the test you linked also uses some basic items in an ignore list: https://github.com/numpy/numpydoc/blob/e9384ce346359cbec556454ae69c1af44d6a9017/numpydoc/tests/test_xref.py#L200 (so that's something we in any case want to copy) -- 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]
