From c1694b35d424b8fbc4abaff94e607c8d52111b11 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Thu, 24 Aug 2017 17:57:18 +0000
Subject: [PATCH] Docs: improve JS docs for `comment-reply.js`

Props andizer, ireneyoast.
Fixes #41548.


git-svn-id: https://develop.svn.wordpress.org/trunk@41314 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/js/comment-reply.js | 35 +++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/js/comment-reply.js b/src/wp-includes/js/comment-reply.js
index 184726d35e..3ddf7744ce 100644
--- a/src/wp-includes/js/comment-reply.js
+++ b/src/wp-includes/js/comment-reply.js
@@ -1,4 +1,22 @@
+/**
+ * @summary Handles the addition of the comment form.
+ *
+ * @since 2.7.0
+ *
+ * @type {Object}
+ */
 var addComment = {
+	/**
+	 * @summary Retrieves the elements corresponding to the given IDs.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param {string} commId The comment ID.
+	 * @param {string} parentId The parent ID.
+	 * @param {string} respondId The respond ID.
+	 * @param {string} postId The post ID.
+	 * @returns {boolean} Always returns false.
+	 */
 	moveForm: function( commId, parentId, respondId, postId ) {
 		var div, element, style, cssHidden,
 			t           = this,
@@ -30,6 +48,11 @@ var addComment = {
 		parent.value = parentId;
 		cancel.style.display = '';
 
+		/**
+		 * @summary Puts back the comment, hides the cancel button and removes the onclick event.
+		 *
+		 * @returns {boolean} Always returns false.
+		 */
 		cancel.onclick = function() {
 			var t       = addComment,
 				temp    = t.I( 'wp-temp-form-div' ),
@@ -48,8 +71,8 @@ var addComment = {
 		};
 
 		/*
-		 * Set initial focus to the first form focusable element.
-		 * Try/catch used just to avoid errors in IE 7- which return visibility
+		 * Sets initial focus to the first form focusable element.
+		 * Uses try/catch just to avoid errors in IE 7- which return visibility
 		 * 'inherit' when the visibility value is inherited from an ancestor.
 		 */
 		try {
@@ -90,6 +113,14 @@ var addComment = {
 		return false;
 	},
 
+	/**
+	 * @summary Returns the object corresponding to the given ID.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param {string} id The ID.
+	 * @returns {Element} The element belonging to the ID.
+	 */
 	I: function( id ) {
 		return document.getElementById( id );
 	}