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.

@HimanshuAwasthi95 @TomAugspurger, Made the suggested changes. Please Review. @Tushar987 Did you push your changes with the PEP8 fixes (the spaces before the `=`, so `p = ...`)?  Oh, also the `datetime.today` change. I'm guessing you just need to push :) @TomAugspurger, Sorry! forgot to push changes. Please review.
 Looks good, thanks! Hmm, I also recently merged PR for `daysinmonth`: https://github.com/pandas-dev/pandas/pull/20295 
Probably we should try to consolidate both (and let them have a shared docstring)