DOC iteritems docstring update and examples
State: closed

Updated iteritems docstring to start with an infinitive and added a short example

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
Hello @Ecboxer! Thanks for updating the PR.

 - In the file [`pandas/core/frame.py`](https://github.com/Ecboxer/pandas/blob/d8e5370e5660d15acfeaa153aed2a25c0fa31694/pandas/core/frame.py), following                are the PEP8 issues :
> [Line 784:80](https://github.com/Ecboxer/pandas/blob/d8e5370e5660d15acfeaa153aed2a25c0fa31694/pandas/core/frame.py#L784): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)
> [Line 796:80](https://github.com/Ecboxer/pandas/blob/d8e5370e5660d15acfeaa153aed2a25c0fa31694/pandas/core/frame.py#L796): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (82 > 79 characters)
> [Line 797:80](https://github.com/Ecboxer/pandas/blob/d8e5370e5660d15acfeaa153aed2a25c0fa31694/pandas/core/frame.py#L797): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (88 > 79 characters)




##### Comment last updated on September 25, 2018 at 14:12 Hours UTC
You can run the validation script locally FYI. `python scripts/validate_docstring.py pandas.DataFrame.iteritems` I think.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=h1) Report
> Merging [#22658](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/27de8e692f7bf3c2efdd9c2d49ec589c29fd74be?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/22658/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #22658   +/-   ##
=======================================
  Coverage   92.18%   92.18%           
=======================================
  Files         169      169           
  Lines       50820    50820           
=======================================
  Hits        46850    46850           
  Misses       3970     3970
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.6% <ø> (ø)` | :arrow_up: |
| #single | `42.38% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/22658/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.2% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/22658/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.67% <0%> (ø)` | :arrow_up: |
| [pandas/core/reshape/melt.py](https://codecov.io/gh/pandas-dev/pandas/pull/22658/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS9tZWx0LnB5) | `97.34% <0%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=footer). Last update [27de8e6...d8e5370](https://codecov.io/gh/pandas-dev/pandas/pull/22658?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@Ecboxer do you have time to update?
Can you run the validation script? I think the output in the tests is not accurate.

You can do it by `./scripts/validate_docstrings.py pandas.DataFrame.iteritems` (you need pandas compiled), and it should say everything is ok.
> Can you run the validation script? I think the output in the tests is not accurate.
> 
> You can do it by `./scripts/validate_docstrings.py pandas.DataFrame.iteritems` (you need pandas compiled), and it should say everything is ok.

When I run scripts/validate_docstrings.py pandas.DataFrame.iteritems I get the following error under #Validation#
Errors found:
	No Returns section found
(When I renamed Yields to Returns, I would get No Yields section found). Should I make some sort of empty Returns section?
If that's the only error, ignore it, it may be an error in the validation script.

I'd just make a quick update if you don't mind. Instead of using `\\n` in the code to escape the backslash, I think it'd be more readable if we set the docstring as a raw string with (`r"""` at the beginning). And may be we can set `end='\n\n'`? that would add a blank line between the two items (I didn't realised that `end='\n'` is actually the default, so it's actually doing nothing now). If you think the `\n\n` it's adding too much complexity, just get rid of the `end` parameter.

Thanks!
> If that's the only error, ignore it, it may be an error in the validation script.
> 
> I'd just make a quick update if you don't mind. Instead of using `\\n` in the code to escape the backslash, I think it'd be more readable if we set the docstring as a raw string with (`r"""` at the beginning). And may be we can set `end=`\n\n`? that would add a blank line between the two items (I didn't realised that`end='\n'`is actually the default, so it's actually doing nothing now). If you think the`\n\n`it's adding too much complexity, just get rid of the`end` parameter.
> 
> Thanks!

I tried it with the end='\n\n' but there was another Validation error for 
Errors found:
	Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
I've dropped the end parameter, because I'm not sure how to get around that test.
@Ecboxer Thanks!