From 1d4fa31a9935d1c82cb749b90edd2bceb78c8859 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Thu, 24 Aug 2017 17:54:22 +0000
Subject: [PATCH] Docs: improve JS docs for `bookmarklet.js`

Props andizer, ireneyoast.
Fixes #41547.


git-svn-id: https://develop.svn.wordpress.org/trunk@41313 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/js/bookmarklet.js | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/wp-admin/js/bookmarklet.js b/src/wp-admin/js/bookmarklet.js
index fe8e74a0c2..b1d1a5860e 100644
--- a/src/wp-admin/js/bookmarklet.js
+++ b/src/wp-admin/js/bookmarklet.js
@@ -1,3 +1,15 @@
+/**
+ * @summary Creates a form with a URL, title, and content based on the current opened URL and the content of the associated web page.
+ *
+ * @since 4.2.0
+ *
+ * @param {window} window The window.
+ * @param {document} document The document.
+ * @param {string} href The current opened URL.
+ * @param {string} pt_url The URL to post the content to.
+ *
+ * @returns {void}
+ */
 ( function( window, document, href, pt_url ) {
 	var encURI = window.encodeURIComponent,
 		form = document.createElement( 'form' ),
@@ -13,6 +25,7 @@
 
 	if ( href.match( /^https?:/ ) ) {
 		pt_url += '&u=' + encURI( href );
+		// Check whether the unencoded url and the encoded url use the same protocol.
 		if ( href.match( /^https:/ ) && pt_url.match( /^http:/ ) ) {
 			canPost = false;
 		}
@@ -52,6 +65,16 @@
 		return;
 	}
 
+	/**
+	 * @summary Creates a hidden input field and sets its name and value.
+	 *
+	 * @since 4.2.0
+	 *
+	 * @param name The input field name.
+	 * @param value The input field value.
+	 *
+	 * @returns {void}
+	 */
 	function add( name, value ) {
 		if ( typeof value === 'undefined' ) {
 			return;