Docs: Add PostsPerPage XML doc

[GaryJones]

See #1722.

[GaryJones]

I adapted the wording from the sniff, but adjusted it to remove the reference to high post counts coming from the use of posts_per_page = -1. See #1638 for context around this.

[jrfnl]

Hi @GaryJones Thanks for creating these docs.

I've left some feedback inline.

Aside from that:

• The "valid" and "invalid" code samples don't mirror each other.
  What I mean by this is that devs - based on the samples here - could get the impression that using _query_posts() is always a bad thing, while using $query_args['key'] is always a good thing.
  I think having a good/bad example for each way to set the keys would be a good idea.
• The second code comparison is missing <em> tags for all code samples.

I'm also wondering whether the code comparison split on the key used is actually needed or that these could just be combined into one which shows both keys.

Or maybe better yet: whether there should be separate code comparisons for each way to set the keys. That would mean three code comparisons:

1. Array initialization example.
2. Adding/overloading a key in an array example.
3. _query_posts() example.

[jrfnl]

@GaryJones Just wondering if you'll have a chance to finish this off in the near future.
I'd like to release WPCS 2.2.0 soon and it would be great if this PR could be included.

[GaryJones]

I'm working on this today / tomorrow.

[GaryJones]

I'm also wondering whether the code comparison split on the key used is actually needed or that these could just be combined into one which shows both keys.

Or maybe better yet: whether there should be separate code comparisons for each way to set the keys. That would mean three code comparisons:

I've kept them split as is for now, but I'd be OK with merging them into a single valid + invalid comparisons.

[jrfnl]

@GaryJones Looks like something went wrong with your cross-branch merging as this PR now seems to contains all the changes since WCEU.... Could you please try to fix this ? If you need help getting the branch cleaned up, please let me know.

[jrfnl]

@GaryJones I've had a look at just the doc file, presuming that's the only chance in this PR.

Other than my reply about the placement of the info around the default limit, it all looks good to me.

Once the branch is fixed, I'm happy to approve and merge this.

[GaryJones]

Looks like something went wrong with your cross-branch merging as this PR now seems to contains all the changes since WCEU

@jrfnl Rebased into a single commit, and fixed the branch issue - all clean again :-)

[jrfnl]

Thanks @GaryJones ! Merging now.