Github user mortada commented on the issue:
https://github.com/apache/spark/pull/15053
But that's what this PR is supposed to fix, the problem that the docstring
for each individual method is not self-contained :)
I think I now see where I was confused - it seems like we are assuming the
user would be looking at the package level docstring? I don't think that's the
typical workflow.
I think the user would be looking at the docstring of one method and expect
the docstring to explain how the method works. (hence the example with `numpy`
I posted above
https://github.com/apache/spark/pull/15053#issuecomment-247906649)
For instance in `ipython` if you do `DataFrame.join?` it would bring up the
docstring for the method `join()`, and it just seems really odd that it'd have
everything including: function signature and parameters, explanation for how it
works, example usage ... except for how to construct the very input data you
need to interact with the example
I don't think the user would know that the input DataFrame in the example
is somehow defined in the package level docstring.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org
For additional commands, e-mail: reviews-h...@spark.apache.org
