pandas.Series.dt.total_seconds() documentation confusing

Code Sample, a copy-pastable example if possible

import pandas as pd

series = pd.Series(pd.datetime(2017, 10, 30))

# Try with regular datetime Series (will fail)
series.dt.total_seconds()

Output: 
AttributeError: 'DatetimeProperties' object has no attribute 'total_seconds'

# Try with TimeDelta Series (intended use)
series.sub(pd.datetime(2017, 10, 29)).dt.total_seconds()

Output:
0    86400.0
dtype: float64

Problem description

The documentation for pd.Series.dt.total_seconds() is a bit confusing. Reading it, one would expect that this method should work on any Series with the dt accessor. This is incorrect; looking at the API reference for datetimeline properties, it’s made clear that this attribute is only available on timedelta Series.

It might be helpful to make it more clear in the documentation for pd.Series.dt.total_seconds() that the method is only available on timedelta Series. Most people will get to the page by googling “Pandas total_seconds” or something similar; they won’t often see where it falls in the API reference.

Is there any precedence for these kinds of heads-ups? I’m happy to make the documentation change and would like to make sure I follow any existing conventions (if they exist).

Output of pd.show_versions()

INSTALLED VERSIONS

commit: None python: 3.6.3.final.0 python-bits: 64 OS: Darwin OS-release: 16.7.0 machine: x86_64 processor: i386 byteorder: little LC_ALL: None LANG: en_US.UTF-8 LOCALE: en_US.UTF-8

pandas: 0.21.0 pytest: None pip: 9.0.1 setuptools: 36.6.0 Cython: None numpy: 1.13.3 scipy: 1.0.0 pyarrow: None xarray: None IPython: 6.2.1 sphinx: None patsy: 0.4.1 dateutil: 2.6.1 pytz: 2017.3 blosc: None bottleneck: None tables: None numexpr: None feather: None matplotlib: 2.1.0 openpyxl: None xlrd: 1.1.0 xlwt: None xlsxwriter: None lxml: None bs4: None html5lib: 1.0b10 sqlalchemy: None pymysql: None psycopg2: None jinja2: 2.9.6 s3fs: None fastparquet: None pandas_gbq: None pandas_datareader: None

[TomAugspurger]

Hmm, what about just slipping the type in the short description then? Maybe:

     def total_seconds(self):
         """
-        Total duration of each element expressed in seconds.
+        Total duration of each timedelta expressed in seconds.
         """
         return Index(self._maybe_mask_results(1e-9 * self.asi8),
                      name=self.name)

[JesperDramsch]

I believe this has been fixed as good as can be: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.dt.total_seconds.html