Improve the inline documentation for class-wc-order-data-store-custom-table.php

Author: stevegrunwell

includes/class-wc-order-data-store-custom-table.php

@@ -123,8 +123,7 @@ public function delete( &$order, $args = array() ) {
 	 * Read order data.
 	 *
 	 * @param WC_Order $order The order object, passed by reference.
-	 * @param object   $post_object
-	 * @since 1.0.0
+	 * @param object   $post_object The post object.
 	 */
 	protected function read_order_data( &$order, $post_object ) {
 		global $wpdb;
@@ -258,8 +257,9 @@ protected function update_post_meta( &$order ) {
 	/**
 	 * Excerpt for post.
 	 *
-	 * @param  WC_Order $order
-	 * @return string
+	 * @param  WC_Order $order The order object.
+	 *
+	 * @return string The post excerpt.
 	 */
 	protected function get_post_excerpt( $order ) {
 		return $order->get_customer_note();
@@ -268,8 +268,11 @@ protected function get_post_excerpt( $order ) {
 	/**
 	 * Get amount already refunded.
 	 *
-	 * @param  WC_Order
-	 * @return string
+	 * @global $wpdb
+	 *
+	 * @param WC_Order $order The order object.
+	 *
+	 * @return string The refund amount.
 	 */
 	public function get_total_refunded( $order ) {
 		global $wpdb;
@@ -288,8 +291,11 @@ public function get_total_refunded( $order ) {
 	/**
 	 * Get the total tax refunded.
 	 *
-	 * @param  WC_Order
-	 * @return float
+	 * @global $wpdb
+	 *
+	 * @param WC_Order $order The order object.
+	 *
+	 * @return float The total refunded tax.
 	 */
 	public function get_total_tax_refunded( $order ) {
 		global $wpdb;
@@ -309,8 +315,11 @@ public function get_total_tax_refunded( $order ) {
 	/**
 	 * Get the total shipping refunded.
 	 *
-	 * @param  WC_Order
-	 * @return float
+	 * @global $wpdb
+	 *
+	 * @param WC_Order $order The order object.
+	 *
+	 * @return float The total refunded shipping.
 	 */
 	public function get_total_shipping_refunded( $order ) {
 		global $wpdb;
@@ -328,40 +337,58 @@ public function get_total_shipping_refunded( $order ) {
 	}
 
 	/**
-	 * Finds an Order ID based on an order key.
+	 * Finds an order ID based on its order key.
+	 *
+	 * @param string $order_key The order key.
 	 *
-	 * @param string $order_key An order key has generated by
 	 * @return int The ID of an order, or 0 if the order could not be found
 	 */
 	public function get_order_id_by_order_key( $order_key ) {
 		global $wpdb;
-		return $wpdb->get_var( $wpdb->prepare( "SELECT order_id FROM {$wpdb->prefix}woocommerce_orders WHERE order_key = %s", $order_key ) );
+
+		return $wpdb->get_var( $wpdb->prepare(
+			"SELECT order_id FROM {$wpdb->prefix}woocommerce_orders WHERE order_key = %s",
+			$order_key
+		) );
 	}
 
 	/**
 	 * Return count of orders with a specific status.
 	 *
-	 * @param  string $status
-	 * @return int
+	 * @global $wpdb
+	 *
+	 * @param  string $status The post_status to filter orders by.
+	 *
+	 * @return int The number of orders with that status.
 	 */
 	public function get_order_count( $status ) {
 		global $wpdb;
-		return absint( $wpdb->get_var( $wpdb->prepare( "SELECT COUNT( * ) FROM {$wpdb->posts} WHERE post_type = 'shop_order' AND post_status = %s", $status ) ) );
+
+		return absint( $wpdb->get_var( $wpdb->prepare(
+			"SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type = 'shop_order' AND post_status = %s",
+			$status
+		) ) );
 	}
 
 	/**
 	 * Get all orders matching the passed in args.
 	 *
-	 * @see    wc_get_orders()
-	 * @param  array $args
+	 * @see wc_get_orders()
+	 *
+	 * @param array $args {
+	 *   Query arguments. All arguments are optional.
+	 *
+	 *   @var string $type The post type. Default is 'shop_order'.
+	 *   @var
+	 * }
 	 * @return object|array array of orders
 	 */
 	public function get_orders( $args = array() ) {
 		/**
 		 * Generate WP_Query args. This logic will change if orders are moved to
 		 * custom tables in the future.
 		 */
-		$wp_query_args = array(
+		$wp_query_args     = array(
 			'post_type'      => $args['type'] ? $args['type'] : 'shop_order',
 			'post_status'    => $args['status'],
 			'posts_per_page' => $args['limit'],
@@ -370,10 +397,6 @@ public function get_orders( $args = array() ) {
 			'orderby'        => $args['orderby'],
 			'order'          => $args['order'],
 		);
-
-		/**
-		 * wc_customer_query
-		 */
 		$wc_customer_query = array();
 
 		if ( ! empty( $args['customer'] ) ) {
@@ -449,9 +472,10 @@ public function get_orders( $args = array() ) {
 	/**
 	 * Generate meta query for wc_get_orders.
 	 *
-	 * @param  array $values
-	 * @param  string $relation
-	 * @return array
+	 * @param  array  $values   Values to populate the meta query.
+	 * @param  string $relation Optional The query relationship, either "and" or "or". Default is "or".
+	 *
+	 * @return array An array suitable for passing to WP_Query's meta_query argument.
 	 */
 	private function get_orders_generate_customer_meta_query( $values, $relation = 'or' ) {
 		$meta_query = array(
@@ -492,10 +516,11 @@ private function get_orders_generate_customer_meta_query( $values, $relation = '
 	}
 
 	/**
-	 * Get unpaid orders after a certain date,
+	 * Get unpaid orders after a certain date.
 	 *
-	 * @param  int timestamp $date
-	 * @return array
+	 * @param int $date The Unix timestamp used for date filtering.
+	 *
+	 * @return array An array of unpaid orders.
 	 */
 	public function get_unpaid_orders( $date ) {
 		global $wpdb;
@@ -514,8 +539,9 @@ public function get_unpaid_orders( $date ) {
 	/**
 	 * Search order data for a term and return ids.
 	 *
-	 * @param  string $term
-	 * @return array of ids
+	 * @param  string $term The search term.
+	 *
+	 * @return array An array of order IDs.
 	 */
 	public function search_orders( $term ) {
 		global $wpdb;
@@ -526,13 +552,12 @@ public function search_orders( $term ) {
 			$order_ids[] = absint( $term );
 		}
 
-		// @todo add order search capability
-
 		/**
 		 * Searches on meta data can be slow - this lets you choose what fields to search.
-		 * 2.7.0 added _billing_address and _shipping_address meta which contains all address data to make this faster.
-		 * This however won't work on older orders unless updated, so search a few others (expand this using the filter if needed).
-		 * @var array
+		 *
+		 * WooCommerce 2.7.0 added _billing_address and _shipping_address meta which contains all
+		 * address data to make this faster. However, this won't work on older orders unless they
+		 * are updated, so search a few others (expand this using the filter if needed).
 		 */
 		$meta_search_fields = array_map( 'wc_clean', apply_filters( 'woocommerce_shop_order_search_fields', array(
 			// While we are searching the custom table, we will also search meta when filtered for backwards compatibility.
@@ -560,7 +585,8 @@ public function search_orders( $term ) {
 	/**
 	 * Gets information about whether permissions were generated yet.
 	 *
-	 * @param WC_Order|int $order
+	 * @param WC_Order|int $order The order object or ID.
+	 *
 	 * @return bool
 	 */
 	public function get_download_permissions_granted( $order ) {
@@ -572,8 +598,8 @@ public function get_download_permissions_granted( $order ) {
 	/**
 	 * Stores information about whether permissions were generated yet.
 	 *
-	 * @param WC_Order|int $order
-	 * @param bool $set
+	 * @param WC_Order|int $order The order object or ID.
+	 * @param bool         $set   Whether or not the permissions have been generated.
 	 */
 	public function set_download_permissions_granted( $order, $set ) {
 		$order_id = WC_Order_Factory::get_order_id( $order );
@@ -584,7 +610,8 @@ public function set_download_permissions_granted( $order, $set ) {
 	/**
 	 * Gets information about whether sales were recorded.
 	 *
-	 * @param WC_Order|int $order
+	 * @param WC_Order|int $order The order object or ID.
+	 *
 	 * @return bool
 	 */
 	public function get_recorded_sales( $order ) {
@@ -596,8 +623,8 @@ public function get_recorded_sales( $order ) {
 	/**
 	 * Stores information about whether sales were recorded.
 	 *
-	 * @param WC_Order|int $order
-	 * @param bool $set
+	 * @param WC_Order|int $order The order object or ID.
+	 * @param bool         $set   Whether or not the sales have been recorded.
 	 */
 	public function set_recorded_sales( $order, $set ) {
 		$order_id = WC_Order_Factory::get_order_id( $order );
@@ -608,7 +635,8 @@ public function set_recorded_sales( $order, $set ) {
 	/**
 	 * Gets information about whether coupon counts were updated.
 	 *
-	 * @param WC_Order|int $order
+	 * @param WC_Order|int $order The order object or ID.
+	 *
 	 * @return bool
 	 */
 	public function get_recorded_coupon_usage_counts( $order ) {
@@ -621,7 +649,7 @@ public function get_recorded_coupon_usage_counts( $order ) {
 	 * Stores information about whether coupon counts were updated.
 	 *
 	 * @param WC_Order|int $order The order object or ID.
-	 * @param bool         $set   Have coupon counts been updated?
+	 * @param bool         $set   Whether or not the coupon counts have been updated.
 	 */
 	public function set_recorded_coupon_usage_counts( $order, $set ) {
 		$order_id = WC_Order_Factory::get_order_id( $order );
@@ -632,7 +660,8 @@ public function set_recorded_coupon_usage_counts( $order, $set ) {
 	/**
 	 * Gets information about whether stock was reduced.
 	 *
-	 * @param WC_Order|int $order
+	 * @param WC_Order|int $order The order object or ID.
+	 *
 	 * @return bool
 	 */
 	public function get_stock_reduced( $order ) {
@@ -645,7 +674,8 @@ public function get_stock_reduced( $order ) {
 	 * Stores information about whether stock was reduced.
 	 *
 	 * @param WC_Order|int $order The order object or ID.
-	 * @param bool         $set   Has the stock been reduced?
+	 *
+	 * @param bool         $set   Whether or not stock has been reduced.
 	 */
 	public function set_stock_reduced( $order, $set ) {
 		$order_id = WC_Order_Factory::get_order_id( $order );
@@ -656,9 +686,9 @@ public function set_stock_reduced( $order, $set ) {
 	/**
 	 * Get the order type based on Order ID.
 	 *
-	 * @since 1.0.0
-	 * @param int $order_id
-	 * @return string
+	 * @param int $order_id The order ID.
+	 *
+	 * @return string The order post type.
 	 */
 	public function get_order_type( $order_id ) {
 		return get_post_type( $order_id );
@@ -667,10 +697,13 @@ public function get_order_type( $order_id ) {
 	/**
 	 * Populate custom table with data from postmeta, for migrations.
 	 *
-	 * @since 1.0.0
-	 * @param bool $save
-	 * @param bool $delete
-	 * @return bool
+	 * @param WC_Order $order  The order object, passed by reference.
+	 * @param bool     $save   Optional. Whether or not the post meta should be updated. Default
+	 *                         is true.
+	 * @param bool     $delete Optional. Whether or not the post meta should be deleted. Default
+	 *                         is false.
+	 *
+	 * @return WC_Order the order object.
 	 */
 	public function populate_from_meta( &$order, $save = true, $delete = false ) {
 		$table_data = $this->get_order_data_from_table( $order );
@@ -688,6 +721,7 @@ public function populate_from_meta( &$order, $save = true, $delete = false ) {
 					case 'prices_include_tax':
 						$order->set_prices_include_tax( 'yes' === $meta );
 						break;
+
 					default:
 						$order->{"set_{$column}"}( $meta );
 				}
@@ -712,8 +746,7 @@ public function populate_from_meta( &$order, $save = true, $delete = false ) {
 	/**
 	 * Populate order postmeta from a custom table, for rolling back.
 	 *
-	 * @since 1.0.0
-	 * @return void
+	 * @param WC_Order $order The order object, passed by reference.
 	 */
 	public function backfill_postmeta( &$order ) {
 		$data = $this->get_order_data_from_table( $order );
@@ -732,9 +765,7 @@ public function backfill_postmeta( &$order ) {
 	/**
 	 * Query for Orders matching specific criteria.
 	 *
-	 * @since 3.1.0
-	 *
-	 * @param array $query_vars query vars from a WC_Order_Query
+	 * @param array $query_vars Query arguments from a WC_Order_Query.
 	 *
 	 * @return array|object
 	 */