From 4006e4a23334185decdd32a2cfce9e0627f3f53e Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Wed, 13 Nov 2013 11:57:11 +0000
Subject: [PATCH] Inline documentation for hooks in wp-mail.php.

props kpdesign, radices.
fixes #25551.

git-svn-id: https://develop.svn.wordpress.org/trunk@26129 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-mail.php | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/src/wp-mail.php b/src/wp-mail.php
index aab9183783..550c28cac5 100644
--- a/src/wp-mail.php
+++ b/src/wp-mail.php
@@ -14,8 +14,12 @@ require(dirname(__FILE__) . '/wp-load.php');
 if ( ! apply_filters( 'enable_post_by_email_configuration', true ) )
 	wp_die( __( 'This action has been disabled by the administrator.' ) );
 
-/** Allow a plugin to do a complete takeover of Post by Email **/
-do_action('wp-mail.php');
+/**
+ * Fires to allow a plugin to do a complete takeover of Post by Email.
+ *
+ * @since 2.9.0
+ */
+do_action( 'wp-mail.php' );
 
 /** Get the POP3 class with which to access the mailbox. */
 require_once( ABSPATH . WPINC . '/class-pop3.php' );
@@ -176,9 +180,17 @@ for ( $i = 1; $i <= $count; $i++ ) {
 	}
 	$content = trim($content);
 
-	//Give Post-By-Email extending plugins full access to the content
-	//Either the raw content or the content of the last quoted-printable section
-	$content = apply_filters('wp_mail_original_content', $content);
+	/**
+	 * Filter the original content of the email.
+	 *
+	 * Give Post-By-Email extending plugins full access to the content, either
+	 * the raw content, or the content of the last quoted-printable section.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @param string $content The original email content.
+	 */
+	$content = apply_filters( 'wp_mail_original_content', $content );
 
 	if ( false !== stripos($content_transfer_encoding, "quoted-printable") ) {
 		$content = quoted_printable_decode($content);
@@ -194,7 +206,14 @@ for ( $i = 1; $i <= $count; $i++ ) {
 
 	$content = trim($content);
 
-	$post_content = apply_filters('phone_content', $content);
+	/**
+	 * Filter the content of the post submitted by email before saving.
+	 *
+	 * @since 1.2.0
+	 *
+	 * @param string $content The email content.
+	 */
+	$post_content = apply_filters( 'phone_content', $content );
 
 	$post_title = xmlrpc_getposttitle($content);
 
@@ -213,7 +232,14 @@ for ( $i = 1; $i <= $count; $i++ ) {
 	if ( empty( $post_ID ) )
 		continue;
 
-	do_action('publish_phone', $post_ID);
+	/**
+	 * Fires after a post submitted by email is published.
+	 *
+	 * @since 1.2.0
+	 *
+	 * @param int $post_ID The post ID.
+	 */
+	do_action( 'publish_phone', $post_ID );
 
 	echo "\n<p>" . sprintf(__('<strong>Author:</strong> %s'), esc_html($post_author)) . '</p>';
 	echo "\n<p>" . sprintf(__('<strong>Posted title:</strong> %s'), esc_html($post_title)) . '</p>';