Improve docblock comments in various functions

* Added missing param tags to functions
* Added comments to `wc_get_attachment_image_attributes` and
`wc_prepare_attachment_for_js`
* Fixed return type value for functions where it says bool but the code
returns array
* Renamed boolean to bool

includes/wc-core-functions.php

@@ -51,6 +51,8 @@ add_filter( 'woocommerce_short_description', 'do_shortcode', 11 ); // AFTER wpau
  *
  * Returns a new order object on success which can then be used to add additional data.
  *
+ * @param  array $args
+ *
  * @return WC_Order on success, WP_Error on failure.
  */
 function wc_create_order( $args = array() ) {

includes/wc-coupon-functions.php

@@ -43,7 +43,7 @@ function wc_get_coupon_type( $type = '' ) {
  * Coupon types that apply to individual products. Controls which validation rules will apply.
  *
  * @since  2.5.0
- * @return bool
+ * @return array
  */
 function wc_get_product_coupon_types() {
 	return (array) apply_filters( 'woocommerce_product_coupon_types', array( 'fixed_product', 'percent_product' ) );
@@ -53,7 +53,7 @@ function wc_get_product_coupon_types() {
  * Coupon types that apply to the cart as a whole. Controls which validation rules will apply.
  *
  * @since  2.5.0
- * @return bool
+ * @return array
  */
 function wc_get_cart_coupon_types() {
 	return (array) apply_filters( 'woocommerce_cart_coupon_types', array( 'fixed_cart', 'percent' ) );
@@ -65,7 +65,7 @@ function wc_get_cart_coupon_types() {
  *
  * @since  2.5.0
  *
- * @return bool
+ * @return array
  */
 function wc_coupons_enabled() {
 	return apply_filters( 'woocommerce_coupons_enabled', 'yes' === get_option( 'woocommerce_enable_coupons' ) );

includes/wc-formatting-functions.php

@@ -179,7 +179,7 @@ function wc_format_refund_total( $amount ) {
  *
  * @param  float|string $number Expects either a float or a string with a decimal separator only (no thousands)
  * @param  mixed $dp number of decimal points to use, blank to use woocommerce_price_num_decimals, or false to avoid all rounding.
- * @param  boolean $trim_zeros from end of string
+ * @param  bool $trim_zeros from end of string
  * @return string
  */
 function wc_format_decimal( $number, $dp = false, $trim_zeros = false ) {

includes/wc-page-functions.php

@@ -78,6 +78,10 @@ function wc_get_page_permalink( $page ) {
  *
  * Gets the URL for an endpoint, which varies depending on permalink settings.
  *
+ * @param  string $endpoint
+ * @param  string $value
+ * @param  string $permalink
+ *
  * @return string
  */
 function wc_get_endpoint_url( $endpoint, $value = '', $permalink = '' ) {

includes/wc-product-functions.php

@@ -441,7 +441,7 @@ function wc_scheduled_sales() {
 add_action( 'woocommerce_scheduled_sales', 'wc_scheduled_sales' );
 
 /**
- * wc_get_attachment_image_attributes function.
+ * Get attachment image attributes.
  *
  * @access public
  * @param array $attr
@@ -458,7 +458,7 @@ add_filter( 'wp_get_attachment_image_attributes', 'wc_get_attachment_image_attri
 
 
 /**
- * wc_prepare_attachment_for_js function.
+ * Prepare attachment for JavaScript.
  *
  * @access public
  * @param array $response

includes/wc-template-functions.php

@@ -448,7 +448,7 @@ if ( ! function_exists( 'woocommerce_page_title' ) ) {
 	/**
 	 * woocommerce_page_title function.
 	 *
-	 * @param  boolean $echo
+	 * @param  bool $echo
 	 * @return string
 	 */
 	function woocommerce_page_title( $echo = true ) {
@@ -1145,6 +1145,9 @@ if ( ! function_exists( 'woocommerce_comments' ) ) {
 	 * Output the Review comments template.
 	 *
 	 * @subpackage	Product
+	 * @param WP_Comment $comment
+	 * @param array $args
+	 * @param int $depth
 	 */
 	function woocommerce_comments( $comment, $args, $depth ) {
 		$GLOBALS['comment'] = $comment;
@@ -1256,9 +1259,9 @@ if ( ! function_exists( 'woocommerce_cross_sell_display' ) ) {
 	/**
 	 * Output the cart cross-sells.
 	 *
-	 * @param  integer $posts_per_page
+	 * @param  int $posts_per_page (default: 2)
-	 * @param  integer $columns
+	 * @param  int $columns (default: 2)
-	 * @param  string $orderby
+	 * @param  string $orderby (default: 'rand')
 	 */
 	function woocommerce_cross_sell_display( $posts_per_page = 2, $columns = 2, $orderby = 'rand' ) {
 		wc_get_template( 'cart/cross-sells.php', array(
@@ -1290,6 +1293,7 @@ if ( ! function_exists( 'woocommerce_mini_cart' ) ) {
 	/**
 	 * Output the Mini-cart - used by cart widget.
 	 *
+	 * @param array $args
 	 */
 	function woocommerce_mini_cart( $args = array() ) {
 
@@ -1311,6 +1315,7 @@ if ( ! function_exists( 'woocommerce_login_form' ) ) {
 	 * Output the WooCommerce Login Form.
 	 *
 	 * @subpackage	Forms
+	 * @param array $args
 	 */
 	function woocommerce_login_form( $args = array() ) {
 
@@ -1342,6 +1347,8 @@ if ( ! function_exists( 'woocommerce_breadcrumb' ) ) {
 
 	/**
 	 * Output the WooCommerce Breadcrumb.
+	 *
+	 * @param array $args
 	 */
 	function woocommerce_breadcrumb( $args = array() ) {
 		$args = wp_parse_args( $args, apply_filters( 'woocommerce_breadcrumb_defaults', array(

includes/wc-term-functions.php

@@ -457,10 +457,10 @@ add_filter( 'terms_clauses', 'wc_terms_clauses', 10, 3 );
 /**
  * Function for recounting product terms, ignoring hidden products.
  *
- * @param  array  $terms
+ * @param  array $terms
- * @param  string  $taxonomy
+ * @param  string $taxonomy
- * @param  boolean $callback
+ * @param  bool $callback
- * @param  boolean $terms_are_term_taxonomy_ids
+ * @param  bool $terms_are_term_taxonomy_ids
  */
 function _wc_term_recount( $terms, $taxonomy, $callback = true, $terms_are_term_taxonomy_ids = true ) {
 	global $wpdb;