diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py
index 491fefe8efee0..d69119d757d70 100644
--- a/pandas/core/indexes/datetimes.py
+++ b/pandas/core/indexes/datetimes.py
@@ -1706,9 +1706,69 @@ def freq(self, value):
                                   "The microseconds of the datetime")
     nanosecond = _field_accessor('nanosecond', 'ns',
                                  "The nanoseconds of the datetime")
-    weekofyear = _field_accessor('weekofyear', 'woy',
-                                 "The week ordinal of the year")
+    _weekofyear_doc = """
+    The week ordinal of the year.
+
+    Return the week ordinal of the year. Note that there can be
+    counter intuitive edge cases around a year change. For example
+    the first of january could be in week 52 of the previous year.
+    Monday indicates the start of a new week. This method is available
+    on both Series with datetime values or DatetimeIndex.
+
+    Returns
+    -------
+    ndarry
+        Containing integers indicating the week number.
+
+    See Also
+    --------
+    pandas.Series.dt.week : Identical method.
+    pandas.Series.dt.weekofyear : Identical method.
+
+    Examples
+    --------
+    >>> dates = pd.date_range("2016-12-31", "2017-01-08", freq="D")
+    >>> s = pd.Series(dates)
+    >>> pd.DataFrame({'dt': s, 'week': s.dt.week, 'day': s.dt.strftime("%A")})
+              dt  week        day
+    0 2016-12-31    52   Saturday
+    1 2017-01-01    52     Sunday
+    2 2017-01-02     1     Monday
+    3 2017-01-03     1    Tuesday
+    4 2017-01-04     1  Wednesday
+    5 2017-01-05     1   Thursday
+    6 2017-01-06     1     Friday
+    7 2017-01-07     1   Saturday
+    8 2017-01-08     1     Sunday
+
+    Note `pandas.Series.dt.week`/`pandas.Series.dt.weekofyear` are the same.
+
+    >>> s.dt.week
+    0    52
+    1    52
+    2     1
+    3     1
+    4     1
+    5     1
+    6     1
+    7     1
+    8     1
+    dtype: int64
+    >>> s.dt.weekofyear
+    0    52
+    1    52
+    2     1
+    3     1
+    4     1
+    5     1
+    6     1
+    7     1
+    8     1
+    dtype: int64
+    """
+    weekofyear = _field_accessor('weekofyear', 'woy', _weekofyear_doc)
     week = weekofyear
+
     dayofweek = _field_accessor('dayofweek', 'dow',
                                 "The day of the week with Monday=0, Sunday=6")
     weekday = dayofweek