Docs: Correct parameter and return types for some comment functions.

This commit corrects some parameter type issues concerning arrays. More specifically:

* `separate_comments()` now correctly indicates that it returns an array of `WP_Comment` objects, keyed by their string types.
* `_close_comments_for_old_posts()` now correctly indicates that it both takes and returns an array of `WP_Post` objects.

Follow-up to [8892], [8897], [8949], [32587], [42876].

Props justlevine, johnbillion.
See #63268.

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

Author: SergeyBiryukov

src/wp-includes/comment.php

@@ -932,8 +932,8 @@ function wp_check_comment_flood( $is_flood, $ip, $email, $date, $avoid_die = fal
  *
  * @since 2.7.0
  *
- * @param WP_Comment[] $comments Array of comments
- * @return WP_Comment[] Array of comments keyed by comment_type.
+ * @param WP_Comment[] $comments Array of comments.
+ * @return array<string, WP_Comment[]> Array of comments keyed by comment type.
  */
 function separate_comments( &$comments ) {
 	$comments_by_type = array(
@@ -3436,9 +3436,9 @@ function _prime_comment_caches( $comment_ids, $update_meta_cache = true ) {
  * @since 2.7.0
  * @access private
  *
- * @param WP_Post  $posts Post data object.
- * @param WP_Query $query Query object.
- * @return array
+ * @param WP_Post[] $posts Array of post objects.
+ * @param WP_Query  $query Query object.
+ * @return WP_Post[]
  */
 function _close_comments_for_old_posts( $posts, $query ) {
 	if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) ) {