DOC: to_datetime works real differently on DataFrames vs other datatypes

[nielsbom]

Location of the documentation

• https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html
• https://pandas.pydata.org/docs/dev/reference/api/pandas.to_datetime.html?highlight=to_datetime

Documentation problem

The to_datetime method does something wildly different on strings or Series vs DataFrames. This caught me by surprise and I think it would help if the documentation reflected this more clearly.

Suggested fix for documentation

Something along the lines of:

For most datatypes given to the to_datetime method it creates datetime objects out of strings. If to_datetime is given a dataframe it does something quite different: it combines columns that contain year, month and day information into datetime objects.

[mzeitlin11]

Thanks for reporting this @nielsbom - agreed further documentation would be helpful. There's an outstanding pr to fix some issues (#42244), but don't think it will completely handle what you mention.

[Dr-Irv]

Two things to change in the docs:

1. For the description of arg, indicate that if it is a DataFrame, we are expecting certain column names (minimally "year", "month", "day"), as discussed in the first example
2. For the return type, indicate that if a DataFrame is passed, the result is a Series

[abatomunkuev]

@Dr-Irv Hello, I would like to work on this issue.

[abatomunkuev]

take

[abatomunkuev]

@mzeitlin11 Hello! I have created a Pull Request :)