DOC:Use of "Yields" for documentation of DataFrame.iteritems()

[sameshl]

changed Returns to Yields

closes #27860

[gfyoung]

@datapythonista @WillAyd : The fix looks good, but the documentation checks seem to be failing.

[jorisvandenbossche]

See the also the discussion on the issue: #27860. Someone will need to understand why the docstring validation sees iteritems and items differently

[jorisvandenbossche]

Ah, it is because iteritems does return self.items() to do the same, therefore the docstring validation sees 'return' and thinks it needs to return something. See logic in

https://github.com/pandas-dev/pandas/blob/master/scripts/validate_docstrings.py#L529-L562

That's of course a bit brittle. @datapythonista I suppose the easiest here is to ignore that rule?
But currently we can only fully ignore a rule or not in code_checks ?

[datapythonista]

Since we're Python 3 only now, my preference is to use yield from self.items() instead of return self.items(), and that should fix the doc validation I think.

[jorisvandenbossche]

@sameshl you can actually remove this % Yields now, and directly edit this in the docstring above. This was only done so that items and iteritems could have a different title in the docstring (returns vs yields)

[sameshl]

Ahh. Nice suggestion @jorisvandenbossche. Will make the required change.

[jorisvandenbossche]

thanks @datapythonista that indeed seems a good idea

[datapythonista]

looks good, thanks @sameshl

I think it'd probably be cleaner if def items had the docstring directly (just a normal docstring), and def iteritems uses @Appender(DataFrame.items) (I think that's what we use in these cases).

Didn't check in detail if that makes sense for sure, and happy to do that in a follow up PR.

[jorisvandenbossche]

Thanks @sameshl !

[sameshl]

Glad to help! @jorisvandenbossche