Make wpList easier to contribute to

[obenland]

I wanted to use wpList for the plugin directory rewrite to take advantage of the built-in data and DOM manipulation but was confronted with a very hard to understand code base with little to no documentation.

I took the time to expand variable names and add some documentation as I waded through the file, learning and understanding what it does. Please find attached patch with the (preliminary) results.
This might muddy some of the file's blame history, but I think it's a decent price to pay for some documentation there, leading to more than a handful of people understanding what it even does in the first place.

[obenland]

@helen I'd like to proceed with this to make wp-lists easier to work with and contribute to in the future. You mentioned that we should try to avoid a total refactor in ​a couple of places and while this is not a refactor but just a prettification, I still wanted to give you an opportunity to veto if you see issues with it.

[rachelbaker]

@obenland this is amazingly helpful. Thank you for doing this. Any reason this ticket (other than time) didn't make 4.6?

[obenland]

I wanted to make sure 2 had a chance to be addressed

[helen]

I do not have any problems with docs/cleanup, just want a second eye on the docs (formatting and content) for peace of mind.

[obenland]

Updated patch to reflect changes in 4.6.

@DrewAPicture, would you mind giving it a final look-over?

[helen]

#34917 was marked as a duplicate.

[helen]

Whenever this gets committed, please give @rommelxcastro props for the parallel work he put into #34917.

[DrewAPicture]

@obenland Looks pretty good. It would be nice to have descriptions on all of the @returns notations in addition to the types.

[obenland]

In 38599:

Make wpList easier to contribute to.

Uses more semantic variable names and adds function and inline documentation.

Props rommelxcastro for parallel work in #34917.
Fixes #36264.