Introduce WP_Comment class to model/strongly-type rows from the comments database table. Inclusion of this class is a pre-req for some more general comment cleanup and sanity.

* Takes inspiration from `WP_Post` and adds sanity to comment caching. 
* Clarifies when the current global value for `$comment` is returned. The current implementation in `get_comment()` introduces side effects and an occasion stale global value for `$comment` when comment caches are cleaned.
* Strongly-types `@param` docs
* This class is marked `final` for now

Props wonderboymusic, nacin.

See #32619.


git-svn-id: https://develop.svn.wordpress.org/trunk@33891 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/feed.php

@@ -264,7 +264,8 @@ function comments_link_feed() {
  *
  * @since 2.5.0
  *
- * @param int|object $comment_id Optional comment object or id. Defaults to global comment object.
+ * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+ *                            user email, WP_User object, WP_Post object, or WP_Comment object.
  */
 function comment_guid($comment_id = null) {
 	echo esc_url( get_comment_guid($comment_id) );
@@ -275,7 +276,8 @@ function comment_guid($comment_id = null) {
  *
  * @since 2.5.0
  *
- * @param int|object $comment_id Optional comment object or id. Defaults to global comment object.
+ * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+ *                            user email, WP_User object, WP_Post object, or WP_Comment object.
  * @return false|string false on failure or guid for comment on success.
  */
 function get_comment_guid($comment_id = null) {