DataFrame.stack() DataFrame.unstack() documentation/behavior

[lodagro]

DataFrame.stack() and DataFrame.unstack() methods require docstring update.

DataFrame.stack() docstring mentions that method converts DataFrame to Series, and returns a Series. This is only the case when columns has only one level. In case columns has multiple levels, method returns a DataFrame.

DataFrame.unstack() docstring is mainly a copy of the Series.unstack() docstring, example should operate on a DataFrame and not a Series.
Concerning the behavior, when the DataFrame index is a single level one, unstack() raises:

AttributeError: `Index` object has no attribute `levels`

DataFrame.unstack() assumes a DataFrame with a multilevel index, it can not operate on single level index, maybe the method could return a Series in case unstack() operates on DataFrame with single level index, similar as stack() does in case of single level columns?

[lodagro]

Noticed that issue #477 already describes fact that DataFrame.unstack() raises exception in case of single level row index, the issue does not mention documentation.

[wesm]

Made a pass over these docstrings. Looking good

[GuillaumeDesforges]

DataFrame.unstack() assumes a DataFrame with a multilevel index, it can not operate on single level index, maybe the method could return a Series in case unstack() operates on DataFrame with single level index, similar as stack() does in case of single level columns?

Any update about that ? Would be helpful !