DOC: update the Period.days_in_month docstring
- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [ ] It has been proofread on language by another sprint participant

```
################################################################################
################### Docstring (pandas.Period.days_in_month)  ###################
################################################################################

Get the total number of days in the month that this period falls on.

Returns
-------
int

See Also
--------
Period.daysinmonth : Returns the number of days in the month.
DatetimeIndex.daysinmonth : Return the number of days in the month.
calendar.monthrange : Return a tuple containing weekday
    (0-6 ~ Mon-Sun) and number of days (28-31).

Examples
--------
>>> p= pd.Period('2018-2-17')
>>> p.days_in_month
28

>>> import datetime
>>> pd.Period(datetime.datetime.today(), freq= 'B').days_in_month
31

Handles the leap year case as well:

>>> p= pd.Period('2016-2-17')
>>> p.days_in_month
29

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found
```

* Short summary summarises pretty much all the characteristics of this attribute.
