Index: trunk/src/bp-core/classes/class-bp-email.php
===================================================================
--- trunk/src/bp-core/classes/class-bp-email.php	(revision 13372)
+++ trunk/src/bp-core/classes/class-bp-email.php	(revision 13892)
@@ -1,5 +1,5 @@
 <?php
 /**
- * Core component classes.
+ * Represents an email that will be sent to member(s).
  *
  * @package BuddyPress
@@ -7,13 +7,14 @@
  */
 
-// Exit if accessed directly
+// Exit if accessed directly.
 defined( 'ABSPATH' ) || exit;
 
 /**
- * Represents an email that will be sent to member(s).
+ * BP_Email class.
  *
  * @since 2.5.0
  */
 class BP_Email {
+
 	/**
 	 * Addressee details (BCC).
@@ -66,5 +67,5 @@
 	 * @since 2.5.0
 	 *
-	 * @var BP_Email_Sender Sender details.
+	 * @var BP_Email_Sender
 	 */
 	protected $from = null;
@@ -82,7 +83,9 @@
 	 * Email headers.
 	 *
-	 * @since 2.5.0
-	 *
-	 * @var string[] Associative pairing of email header name/value.
+	 * Associative pairing of email header name/value.
+	 *
+	 * @since 2.5.0
+	 *
+	 * @var string[]
 	 */
 	protected $headers = array();
@@ -93,5 +96,5 @@
 	 * @since 2.5.0
 	 *
-	 * @var WP_Post
+	 * @var WP_Post|null
 	 */
 	protected $post_object = null;
@@ -102,5 +105,5 @@
 	 * @since 2.5.0
 	 *
-	 * @var BP_Email_Sender "Reply to" details.
+	 * @var BP_Email_Sender|null
 	 */
 	protected $reply_to = null;
@@ -146,7 +149,9 @@
 	 * Token names and replacement values for this email.
 	 *
-	 * @since 2.5.0
-	 *
-	 * @var string[] Associative pairing of token name (key) and replacement value (value).
+	 * Associative pairing of token name (key) and replacement value (value).
+	 *
+	 * @since 2.5.0
+	 *
+	 * @var string[]
 	 */
 	protected $tokens = array();
@@ -170,5 +175,4 @@
 				$domain = substr( $domain, 4 );
 			}
-
 		} elseif ( function_exists( 'gethostname' ) && gethostname() !== false ) {
 			$domain = gethostname();
@@ -205,5 +209,4 @@
 	}
 
-
 	/*
 	 * Setters/getters.
@@ -228,5 +231,5 @@
 			$property_name = 'content_' . $this->get_content_type();
 
-			if ( ! in_array( $property_name, array( 'content_html', 'content_plaintext', ), true ) ) {
+			if ( ! in_array( $property_name, array( 'content_html', 'content_plaintext' ), true ) ) {
 				$property_name = 'content_html';
 			}
@@ -236,5 +239,4 @@
 			return null;
 		}
-
 
 		/**
@@ -273,5 +275,5 @@
 		 * @since 2.5.0
 		 *
-		 * @param string   $retval        Property value.
+		 * @param mixed    $retval        Property value.
 		 * @param string   $property_name Property name.
 		 * @param string   $transform     How to transform the return value.
@@ -286,4 +288,6 @@
 	 *
 	 * @since 4.0.0
+	 *
+	 * @return string
 	 */
 	public function get_preheader() {
@@ -444,5 +448,6 @@
 	 * @since 2.5.0
 	 *
-	 * @return WP_Post The post.
+	 * @param string $transform Optional. How to transform the return value. Defaults to 'raw'.
+	 * @return WP_Post|null WP_Post object, or null if not set.
 	 */
 	public function get_post_object( $transform = 'raw' ) {
@@ -459,5 +464,5 @@
 	 * @param string $transform Optional. How to transform the return value.
 	 *                          Accepts 'raw' (default) or 'replace-tokens'.
-	 * @return BP_Email_Recipient "Reply to" recipient.
+	 * @return BP_Email_Recipient|null "Reply to" recipient, or null if not set.
 	 */
 	public function get_reply_to( $transform = 'raw' ) {
@@ -474,5 +479,5 @@
 	 * @param string $transform Optional. How to transform the return value.
 	 *                          Accepts 'raw' (default) or 'replace-tokens'.
-	 * @return string Email subject.
+	 * @return string|null Email subject, or null if not set.
 	 */
 	public function get_subject( $transform = 'raw' ) {
@@ -489,5 +494,5 @@
 	 * @param string $transform Optional. How to transform the return value.
 	 *                          Accepts 'raw' (default) or 'replace-tokens'.
-	 * @return string Email template. Assumed to be HTML.
+	 * @return string|null Email template. Assumed to be HTML. Or null if not set.
 	 */
 	public function get_template( $transform = 'raw' ) {
@@ -504,5 +509,5 @@
 	 * @param string $transform Optional. How to transform the return value.
 	 *                          Accepts 'raw' (default) or 'replace-tokens'.
-	 * @return BP_Email_Recipient[] "To" recipients.
+	 * @return BP_Email_Recipient[]|null "To" recipients. Or null if not set.
 	 */
 	public function get_to( $transform = 'raw' ) {
@@ -519,5 +524,6 @@
 	 * @param string $transform Optional. How to transform the return value.
 	 *                          Accepts 'raw' (default) or 'replace-tokens'.
-	 * @return string[] Associative pairing of token name (key) and replacement value (value).
+	 * @return string[]|null Associative pairing of token name (key) and replacement value (value).
+	 *                       Or null if not set.
 	 */
 	public function get_tokens( $transform = 'raw' ) {
@@ -571,7 +577,7 @@
 	 * @param string|array|int|WP_User $bcc_address Either a email address, user ID, WP_User object,
 	 *                                              or an array containing any combination of the above.
-	 * @param string $name Optional. If $bcc_address is a string, this is the recipient's name.
-	 * @param string $operation Optional. If "replace", $to_address replaces current setting (default).
-	 *                          If "add", $to_address is added to the current setting.
+	 * @param string                   $name Optional. If $bcc_address is a string, this is the recipient's name.
+	 * @param string                   $operation Optional. If "replace", $to_address replaces current setting (default).
+	 *                                            If "add", $to_address is added to the current setting.
 	 * @return BP_Email
 	 */
@@ -583,5 +589,4 @@
 				$bcc[] = new BP_Email_Recipient( $address );
 			}
-
 		} else {
 			$bcc[] = new BP_Email_Recipient( $bcc_address, $name );
@@ -620,7 +625,7 @@
 	 * @param string|array|int|WP_User $cc_address Either a email address, user ID, WP_User object,
 	 *                                             or an array containing any combination of the above.
-	 * @param string $name Optional. If $cc_address is a string, this is the recipient's name.
-	 * @param string $operation Optional. If "replace", $to_address replaces current setting (default).
-	 *                          If "add", $to_address is added to the current setting.
+	 * @param string                   $name Optional. If $cc_address is a string, this is the recipient's name.
+	 * @param string                   $operation Optional. If "replace", $to_address replaces current setting (default).
+	 *                                            If "add", $to_address is added to the current setting.
 	 * @return BP_Email
 	 */
@@ -632,5 +637,4 @@
 				$cc[] = new BP_Email_Recipient( $address );
 			}
-
 		} else {
 			$cc[] = new BP_Email_Recipient( $cc_address, $name );
@@ -710,5 +714,5 @@
 	 */
 	public function set_content_type( $content_type ) {
-		if ( ! in_array( $content_type, array( 'html', 'plaintext', ), true ) ) {
+		if ( ! in_array( $content_type, array( 'html', 'plaintext' ), true ) ) {
 			$class        = get_class_vars( get_class() );
 			$content_type = $class['content_type'];
@@ -736,5 +740,5 @@
 	 *
 	 * @param string|array|int|WP_User $email_address Either a email address, user ID, or WP_User object.
-	 * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+	 * @param string                   $name Optional. If $email_address is a string, this is the recipient's name.
 	 * @return BP_Email
 	 */
@@ -768,5 +772,5 @@
 	 * @since 2.5.0
 	 *
-	 * @param WP_Post $post
+	 * @param WP_Post $post Post object.
 	 * @return BP_Email
 	 */
@@ -820,5 +824,5 @@
 	 * @param string|array|int|WP_User $email_address Either a email address, user ID, WP_User object,
 	 *                                                or an array containing any combination of the above.
-	 * @param string $name Optional. If $email_address is a string, this is the recipient's name.
+	 * @param string                   $name Optional. If $email_address is a string, this is the recipient's name.
 	 * @return BP_Email
 	 */
@@ -913,7 +917,7 @@
 	 * @param string|array|int|WP_User $to_address Either a email address, user ID, WP_User object,
 	 *                                             or an array containing any combination of the above.
-	 * @param string $name Optional. If $to_address is a string, this is the recipient's name.
-	 * @param string $operation Optional. If "replace", $to_address replaces current setting (default).
-	 *                          If "add", $to_address is added to the current setting.
+	 * @param string                   $name Optional. If $to_address is a string, this is the recipient's name.
+	 * @param string                   $operation Optional. If "replace", $to_address replaces current setting (default).
+	 *                                            If "add", $to_address is added to the current setting.
 	 * @return BP_Email
 	 */
@@ -925,5 +929,4 @@
 				$to[] = new BP_Email_Recipient( $address );
 			}
-
 		} else {
 			$to[] = new BP_Email_Recipient( $to_address, $name );
@@ -982,5 +985,4 @@
 		return $this;
 	}
-
 
 	/*
