From 676525c2b7f96b6e15b89b12e852c1d83d4627d4 Mon Sep 17 00:00:00 2001 From: Fredrik Forsmo Date: Wed, 6 Jan 2016 17:11:09 +0100 Subject: [PATCH] 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 | 2 ++ includes/wc-coupon-functions.php | 6 +++--- includes/wc-formatting-functions.php | 2 +- includes/wc-page-functions.php | 4 ++++ includes/wc-product-functions.php | 4 ++-- includes/wc-template-functions.php | 15 +++++++++++---- includes/wc-term-functions.php | 8 ++++---- 7 files changed, 27 insertions(+), 14 deletions(-) diff --git a/includes/wc-core-functions.php b/includes/wc-core-functions.php index 598f1bbf53e..f1ea9b9389f 100644 --- a/includes/wc-core-functions.php +++ b/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() ) { diff --git a/includes/wc-coupon-functions.php b/includes/wc-coupon-functions.php index 3a7bf840857..ffa45450e54 100644 --- a/includes/wc-coupon-functions.php +++ b/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' ) ); diff --git a/includes/wc-formatting-functions.php b/includes/wc-formatting-functions.php index 43bebc601bc..a0667b78cec 100644 --- a/includes/wc-formatting-functions.php +++ b/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 ) { diff --git a/includes/wc-page-functions.php b/includes/wc-page-functions.php index f7584641c21..12ec88f1c74 100644 --- a/includes/wc-page-functions.php +++ b/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 = '' ) { diff --git a/includes/wc-product-functions.php b/includes/wc-product-functions.php index 51958723585..6fab3ababad 100644 --- a/includes/wc-product-functions.php +++ b/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 diff --git a/includes/wc-template-functions.php b/includes/wc-template-functions.php index a2d42016918..3a05eac938f 100644 --- a/includes/wc-template-functions.php +++ b/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 integer $columns - * @param string $orderby + * @param int $posts_per_page (default: 2) + * @param int $columns (default: 2) + * @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( diff --git a/includes/wc-term-functions.php b/includes/wc-term-functions.php index d36ff54b6a0..285c874c7cd 100644 --- a/includes/wc-term-functions.php +++ b/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 string $taxonomy - * @param boolean $callback - * @param boolean $terms_are_term_taxonomy_ids + * @param array $terms + * @param string $taxonomy + * @param bool $callback + * @param bool $terms_are_term_taxonomy_ids */ function _wc_term_recount( $terms, $taxonomy, $callback = true, $terms_are_term_taxonomy_ids = true ) { global $wpdb;