DOC: update the Period.qyear docstring (pandas-dev#20333)

* DOC: update the Period.qyear docstring

* DOC: update the Period.qyear docstring

* DOC: update the Period.qyear docstring

* DOC: update the Period.qyear docstring

* update qyear

Signed-off-by: uttamaniket <[email protected]>

* update qyear

Signed-off-by: uttamaniket <[email protected]>

* update qyear

Signed-off-by: uttamaniket <[email protected]>

* update qyear

Signed-off-by: uttamaniket <[email protected]>

* update Period.qyear

Signed-off-by: uttamaniket <[email protected]>

* update Period.qyear

Signed-off-by: uttamaniket <[email protected]>

* update pandas.qyear

Signed-off-by: uttamaniket <[email protected]>

* update qyear

Signed-off-by: uttamaniket <[email protected]>

* Adding extra clarification on how year and qyear are different

* Addressing last comments from @jbrockmendel

Author: uttamaniket

pandas/_libs/tslibs/period.pyx

@@ -1463,6 +1463,45 @@ cdef class _Period(object):
 
     @property
     def qyear(self):
+        """
+        Fiscal year the Period lies in according to its starting-quarter.
+
+        The `year` and the `qyear` of the period will be the same if the fiscal
+        and calendar years are the same. When they are not, the fiscal year
+        can be different from the calendar year of the period.
+
+        Returns
+        -------
+        int
+            The fiscal year of the period.
+
+        See Also
+        --------
+        Period.year : Return the calendar year of the period.
+        
+        Examples
+        --------
+        If the natural and fiscal year are the same, `qyear` and `year` will
+        be the same.
+
+        >>> per = pd.Period('2018Q1', freq='Q')
+        >>> per.qyear
+        2018
+        >>> per.year
+        2018
+
+        If the fiscal year starts in April (`Q-MAR`), the first quarter of
+        2018 will start in April 2017. `year` will then be 2018, but `qyear`
+        will be the fiscal year, 2018.
+
+        >>> per = pd.Period('2018Q1', freq='Q-MAR')
+        >>> per.start_time
+        Timestamp('2017-04-01 00:00:00')
+        >>> per.qyear
+        2018
+        >>> per.year
+        2017
+        """
         base, mult = get_freq_code(self.freq)
         return pqyear(self.ordinal, base)