Index: src/wp-includes/comment.php
===================================================================
--- src/wp-includes/comment.php	(revision 32297)
+++ src/wp-includes/comment.php	(working copy)
@@ -2084,14 +2084,39 @@
 /**
  * Inserts a comment to the database.
  *
- * The available comment data key names are 'comment_author_IP', 'comment_date',
- * 'comment_date_gmt', 'comment_parent', 'comment_approved', and 'user_id'.
+ * Both 'comment_date' and 'comment_date_gmt' values must be specified to set the date manually.
  *
  * @since 2.0.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array $commentdata Contains information on the comment.
+ * @param array $commentdata {
+ *     An array of elements that make up the comment.
+ *
+ *     @type string     $comment_agent        The HTTP user agent of the `$comment_author` when
+ *                                            the comment was submitted. Default empty.
+ *     @type int|string $comment_approved     Whether the comment has been approved. Default 1.
+ *     @type string     $comment_author       The name of the author of the comment. Default empty.
+ *     @type string     $comment_author_email The email address of the `$comment_author`. Default
+ *                                            empty.
+ *     @type string     $comment_author_IP    The IP address of the `$comment_author`. Default
+ *                                            empty.
+ *     @type string     $comment_author_url   The URL address of the `$comment_author`. Default
+ *                                            empty.
+ *     @type string     $comment_content      The content of the comment. Default empty.
+ *     @type string     $comment_date         The date the comment was submitted. Default is the
+ *                                            current time.
+ *     @type string     $comment_date_gmt     The date the comment was submitted in the GMT
+ *                                            timezone. Default is `$comment_date` in the GMT
+ *                                            timezone.
+ *     @type int        $comment_karma        The karma of the comment. Default 0.
+ *     @type int        $comment_parent       The ID of this comment's parent, if any. Default 0.
+ *     @type int        $comment_post_ID      The ID of the post that relates to the comment, if
+ *                                            any. Default empty.
+ *     @type string     $comment_type         The type of comment. Default empty.
+ *     @type int        $user_id              The ID of the user who submitted the comment.
+ *                                            Default 0.
+ * }
  * @return int|bool The new comment's ID on success, false on failure.
  */
 function wp_insert_comment( $commentdata ) {