Update inline docs for wp-admin/includes/upgrade.php

[morganestes]

There are several stubs for documenting upgrade functions with short and long descriptions. This patch is an effort to update those docblocks with accurate descriptions where I can, update blocks that have inaccurate @param and @return info, and add an additional block where one was missing.

[morganestes]

Updated diff with all changes.

[morganestes]

This is the first time I've used Git to create a new branch for a ticket. I didn't realize that trying to create a patch would be so difficult with multiple commits to that branch, but I think I finally got all my changes in the .3.diff patch.

[morganestes]

Better diff from Git with --no-prefix flag.

[DrewAPicture]

In 31246:

Add missing summaries and descriptions for various functions in wp-admin/includes/upgrade.php.

Also generally improve existing parameter, return, and other documentation in various function DocBlocks.

Props morganestes.
Fixes #30825.