From 79115ae6a5e37d101a05b88ec1308be7da3d379a Mon Sep 17 00:00:00 2001
From: Andrew Ozz <azaozz@git.wordpress.org>
Date: Thu, 10 Nov 2011 17:46:23 +0000
Subject: [PATCH] More phpdoc for wp_editor(), see #17144

git-svn-id: https://develop.svn.wordpress.org/trunk@19239 602fd350-edb4-49c9-b593-d223f7449a82
---
 wp-includes/class-wp-editor.php  |  2 +-
 wp-includes/general-template.php | 14 ++++++++++++--
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/wp-includes/class-wp-editor.php b/wp-includes/class-wp-editor.php
index df72592834..aef53c189a 100644
--- a/wp-includes/class-wp-editor.php
+++ b/wp-includes/class-wp-editor.php
@@ -576,7 +576,7 @@ class WP_Editor {
 		var wpActiveEditor;
 
 		jQuery('.wp-editor-wrap').mousedown(function(e){
-	    	wpActiveEditor = this.id.slice(3, -5);
+			wpActiveEditor = this.id.slice(3, -5);
 		});
 
 <?php
diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php
index c2a4910399..fc6aca85a9 100644
--- a/wp-includes/general-template.php
+++ b/wp-includes/general-template.php
@@ -1733,13 +1733,23 @@ function user_can_richedit() {
 }
 
 /**
- * Loads and initializes WP_Editor class if needed, passes the settings for an instance of the editor
+ * Loads and initializes WP_Editor class (if needed), passes the settings for an instance of the editor
  *
+ * Using this function is the proper way to output all needed components for both TinyMCE and Quicktags.
+ * WP_Editor shouldn't be instantiated separately as it keeps track of loaded scripts.
+ * See http://core.trac.wordpress.org/ticket/17144. 
+ * 
+ * NOTE: Once initialized the TinyMCE editor cannot be safely moved in the DOM. For that reason
+ * running wp_editor() inside of a metabox is not a good idea unless only Quicktags is used.
+ * On the post edit screen several actions can be used to include additional editors
+ * containing TinyMCE: 'edit_page_form', 'edit_form_advanced' and 'dbx_post_sidebar'.
+ * See http://core.trac.wordpress.org/ticket/19173 for more information.
+ * 
  * @see wp-includes/class-wp-editor.php
  * @since 3.3
  *
  * @param string $content Initial content for the editor.
- * @param string $editor_id HTML ID attribute value for the textarea and TinyMCE.
+ * @param string $editor_id HTML ID attribute value for the textarea and TinyMCE. Can only be /[a-z]+/.
  * @param array $settings See WP_Editor::editor().
  */
 function wp_editor( $content, $editor_id, $settings = array() ) {