From e7f332f02cac5b17589fcb03b6af2da6f19a712f Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Fri, 7 Nov 2025 10:50:04 +0600 Subject: [PATCH 1/4] Twenty Eleven: Improve PHP DocBlock compliance with documentation standards Updates PHP DocBlocks in Twenty Eleven theme to better align with WordPress PHP Documentation Standards. Changes include: - Use third-person singular verbs in function summaries - Add missing @return tags for better type documentation - Complete @param documentation for widget methods - Ensure proper sentence structure with punctuation - Add missing DocBlock for twentyeleven_theme_options_help() --- .../themes/twentyeleven/inc/theme-options.php | 19 ++++++++++++++++--- .../themes/twentyeleven/inc/widgets.php | 4 ++++ 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/src/wp-content/themes/twentyeleven/inc/theme-options.php b/src/wp-content/themes/twentyeleven/inc/theme-options.php index eb3992ace683a..23e19defe43ac 100644 --- a/src/wp-content/themes/twentyeleven/inc/theme-options.php +++ b/src/wp-content/themes/twentyeleven/inc/theme-options.php @@ -8,7 +8,7 @@ */ /** - * Properly enqueues styles and scripts for our theme options page. + * Enqueues styles and scripts for the theme options page. * * This function is attached to the admin_enqueue_scripts action hook. * @@ -84,7 +84,7 @@ function twentyeleven_option_page_capability( $capability ) { add_filter( 'option_page_capability_twentyeleven_options', 'twentyeleven_option_page_capability' ); /** - * Adds a theme options page to the admin menu, including some help documentation. + * Adds the theme options page to the admin menu, including help documentation. * * This function is attached to the admin_menu action hook. * @@ -107,6 +107,11 @@ function twentyeleven_theme_options_add_page() { } add_action( 'admin_menu', 'twentyeleven_theme_options_add_page' ); +/** + * Adds help documentation to the theme options page. + * + * @since Twenty Eleven 1.0 + */ function twentyeleven_theme_options_help() { $help = '

' . __( 'Some themes provide customization options that are grouped together on a Theme Options screen. If you change themes, options may change or disappear, as they are theme-specific. Your current theme, Twenty Eleven, provides the following Theme Options:', 'twentyeleven' ) . '

' . @@ -144,6 +149,8 @@ function twentyeleven_theme_options_help() { * Returns an array of color schemes registered for Twenty Eleven. * * @since Twenty Eleven 1.0 + * + * @return array An associative array of color scheme options. */ function twentyeleven_color_schemes() { $color_scheme_options = array( @@ -175,6 +182,8 @@ function twentyeleven_color_schemes() { * Returns an array of layout options registered for Twenty Eleven. * * @since Twenty Eleven 1.0 + * + * @return array An associative array of layout options. */ function twentyeleven_layouts() { $layout_options = array( @@ -260,6 +269,8 @@ function twentyeleven_get_default_link_color( $color_scheme = null ) { * Returns the options array for Twenty Eleven. * * @since Twenty Eleven 1.0 + * + * @return array The theme options array. */ function twentyeleven_get_theme_options() { return get_option( 'twentyeleven_theme_options', twentyeleven_get_default_theme_options() ); @@ -372,6 +383,7 @@ function twentyeleven_theme_options_render_page() { * @since Twenty Eleven 1.0 * * @param array $input An array of form input. + * @return array An array of sanitized and validated form output. */ function twentyeleven_theme_options_validate( $input ) { $defaults = twentyeleven_get_default_theme_options(); @@ -487,6 +499,7 @@ function twentyeleven_print_link_color_style() { * @since Twenty Eleven 1.0 * * @param array $existing_classes An array of existing body classes. + * @return array The filtered array of body classes. */ function twentyeleven_layout_classes( $existing_classes ) { $options = twentyeleven_get_theme_options(); @@ -521,7 +534,7 @@ function twentyeleven_layout_classes( $existing_classes ) { add_filter( 'body_class', 'twentyeleven_layout_classes' ); /** - * Implements Twenty Eleven theme options into Customizer + * Implements Twenty Eleven theme options into Customizer. * * @since Twenty Eleven 1.3 * diff --git a/src/wp-content/themes/twentyeleven/inc/widgets.php b/src/wp-content/themes/twentyeleven/inc/widgets.php index 4f77b2abbd175..8594b68eafe83 100644 --- a/src/wp-content/themes/twentyeleven/inc/widgets.php +++ b/src/wp-content/themes/twentyeleven/inc/widgets.php @@ -156,6 +156,10 @@ public function widget( $args, $instance ) { * where any validation should be dealt with. * * @since Twenty Eleven 1.0 + * + * @param array $new_instance New settings for this instance as input by the user. + * @param array $old_instance Old settings for this instance. + * @return array Updated settings to save. */ public function update( $new_instance, $old_instance ) { $instance = $old_instance; From bf87b33952348a33548ed8bbea922707e739e0bb Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Tue, 11 Nov 2025 09:05:45 +0600 Subject: [PATCH 2/4] Updated @since version number for twentyeleven_theme_options_help() Co-authored-by: Stephen A. Bernhardt --- src/wp-content/themes/twentyeleven/inc/theme-options.php | 2 +- src/wp-content/themes/twentyeleven/inc/widgets.php | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/wp-content/themes/twentyeleven/inc/theme-options.php b/src/wp-content/themes/twentyeleven/inc/theme-options.php index 23e19defe43ac..9fa6084ff3159 100644 --- a/src/wp-content/themes/twentyeleven/inc/theme-options.php +++ b/src/wp-content/themes/twentyeleven/inc/theme-options.php @@ -110,7 +110,7 @@ function twentyeleven_theme_options_add_page() { /** * Adds help documentation to the theme options page. * - * @since Twenty Eleven 1.0 + * @since Twenty Eleven 1.3 */ function twentyeleven_theme_options_help() { diff --git a/src/wp-content/themes/twentyeleven/inc/widgets.php b/src/wp-content/themes/twentyeleven/inc/widgets.php index 8594b68eafe83..ae22bca001ceb 100644 --- a/src/wp-content/themes/twentyeleven/inc/widgets.php +++ b/src/wp-content/themes/twentyeleven/inc/widgets.php @@ -157,9 +157,9 @@ public function widget( $args, $instance ) { * * @since Twenty Eleven 1.0 * - * @param array $new_instance New settings for this instance as input by the user. - * @param array $old_instance Old settings for this instance. - * @return array Updated settings to save. + * @param array $new_instance New widget instance. + * @param array $old_instance Original widget instance. + * @return array Updated widget instance. */ public function update( $new_instance, $old_instance ) { $instance = $old_instance; From 54e27a1e994200d66e296814b7c2f45a8517dd09 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Tue, 11 Nov 2025 09:07:39 +0600 Subject: [PATCH 3/4] Added missing @since note for twentyeleven_option_page_capability() Added documentation for twentyeleven_option_page_capability function. --- src/wp-content/themes/twentyeleven/inc/theme-options.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/wp-content/themes/twentyeleven/inc/theme-options.php b/src/wp-content/themes/twentyeleven/inc/theme-options.php index 9fa6084ff3159..2775c702704bf 100644 --- a/src/wp-content/themes/twentyeleven/inc/theme-options.php +++ b/src/wp-content/themes/twentyeleven/inc/theme-options.php @@ -75,6 +75,8 @@ function twentyeleven_theme_options_init() { * By default, only administrators have either of these capabilities, but the desire here is * to allow for finer-grained control for roles and users. * + * @since Twenty Eleven 1.1 + * * @param string $capability The capability used for the page, which is manage_options by default. * @return string The capability to actually use. */ From aef096603d80d4eb6899e0b1eba281d7fb78ae74 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Tue, 25 Nov 2025 10:34:20 -0800 Subject: [PATCH 4/4] Add more specific types and fix a return type --- .../themes/twentyeleven/inc/theme-options.php | 32 +++++++++---------- .../themes/twentyeleven/inc/widgets.php | 6 ++-- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/src/wp-content/themes/twentyeleven/inc/theme-options.php b/src/wp-content/themes/twentyeleven/inc/theme-options.php index 2775c702704bf..e813b506704f4 100644 --- a/src/wp-content/themes/twentyeleven/inc/theme-options.php +++ b/src/wp-content/themes/twentyeleven/inc/theme-options.php @@ -152,7 +152,7 @@ function twentyeleven_theme_options_help() { * * @since Twenty Eleven 1.0 * - * @return array An associative array of color scheme options. + * @return array> An associative array of color scheme options. */ function twentyeleven_color_schemes() { $color_scheme_options = array( @@ -175,7 +175,7 @@ function twentyeleven_color_schemes() { * * @since Twenty Eleven 1.0 * - * @param array $color_scheme_options An associative array of color scheme options. + * @param array> $color_scheme_options An associative array of color scheme options. */ return apply_filters( 'twentyeleven_color_schemes', $color_scheme_options ); } @@ -185,7 +185,7 @@ function twentyeleven_color_schemes() { * * @since Twenty Eleven 1.0 * - * @return array An associative array of layout options. + * @return array> An associative array of layout options. */ function twentyeleven_layouts() { $layout_options = array( @@ -211,7 +211,7 @@ function twentyeleven_layouts() { * * @since Twenty Eleven 1.0 * - * @param array $layout_options An associative array of layout options. + * @param array> $layout_options An associative array of layout options. */ return apply_filters( 'twentyeleven_layouts', $layout_options ); } @@ -221,7 +221,7 @@ function twentyeleven_layouts() { * * @since Twenty Eleven 1.0 * - * @return array An array of default theme options. + * @return array An array of default theme options. */ function twentyeleven_get_default_theme_options() { $default_theme_options = array( @@ -239,7 +239,7 @@ function twentyeleven_get_default_theme_options() { * * @since Twenty Eleven 1.0 * - * @param array $default_theme_options An array of default theme options. + * @param array $default_theme_options An array of default theme options. */ return apply_filters( 'twentyeleven_default_theme_options', $default_theme_options ); } @@ -251,7 +251,7 @@ function twentyeleven_get_default_theme_options() { * * @param string $color_scheme Optional. Color scheme. * Default null (or the active color scheme). - * @return string The default link color. + * @return string|false The default link color, or false if not set. */ function twentyeleven_get_default_link_color( $color_scheme = null ) { if ( null === $color_scheme ) { @@ -272,7 +272,7 @@ function twentyeleven_get_default_link_color( $color_scheme = null ) { * * @since Twenty Eleven 1.0 * - * @return array The theme options array. + * @return array The theme options array. */ function twentyeleven_get_theme_options() { return get_option( 'twentyeleven_theme_options', twentyeleven_get_default_theme_options() ); @@ -385,7 +385,7 @@ function twentyeleven_theme_options_render_page() { * @since Twenty Eleven 1.0 * * @param array $input An array of form input. - * @return array An array of sanitized and validated form output. + * @return array An array of sanitized and validated form output. */ function twentyeleven_theme_options_validate( $input ) { $defaults = twentyeleven_get_default_theme_options(); @@ -415,9 +415,9 @@ function twentyeleven_theme_options_validate( $input ) { * * @since Twenty Eleven 1.0 * - * @param array $output An array of sanitized form output. - * @param array $input An array of un-sanitized form input. - * @param array $defaults An array of default theme options. + * @param array $output An array of sanitized form output. + * @param array $input An array of un-sanitized form input. + * @param array $defaults An array of default theme options. */ return apply_filters( 'twentyeleven_theme_options_validate', $output, $input, $defaults ); } @@ -500,8 +500,8 @@ function twentyeleven_print_link_color_style() { * * @since Twenty Eleven 1.0 * - * @param array $existing_classes An array of existing body classes. - * @return array The filtered array of body classes. + * @param string[] $existing_classes An array of existing body classes. + * @return string[] The filtered array of body classes. */ function twentyeleven_layout_classes( $existing_classes ) { $options = twentyeleven_get_theme_options(); @@ -526,8 +526,8 @@ function twentyeleven_layout_classes( $existing_classes ) { * * @since Twenty Eleven 1.0 * - * @param array $classes An array of body classes. - * @param string $current_layout The current theme layout. + * @param string[] $classes An array of body classes. + * @param string $current_layout The current theme layout. */ $classes = apply_filters( 'twentyeleven_layout_classes', $classes, $current_layout ); diff --git a/src/wp-content/themes/twentyeleven/inc/widgets.php b/src/wp-content/themes/twentyeleven/inc/widgets.php index ae22bca001ceb..4e82cdf6a055e 100644 --- a/src/wp-content/themes/twentyeleven/inc/widgets.php +++ b/src/wp-content/themes/twentyeleven/inc/widgets.php @@ -49,8 +49,8 @@ public function Twenty_Eleven_Ephemera_Widget() { * * @since Twenty Eleven 1.0 * - * @param array $args An array of standard parameters for widgets in this theme. - * @param array $instance An array of settings for this widget instance. + * @param array $args An array of standard parameters for widgets in this theme. + * @param array $instance An array of settings for this widget instance. */ public function widget( $args, $instance ) { $cache = wp_cache_get( 'widget_twentyeleven_ephemera', 'widget' ); @@ -159,7 +159,7 @@ public function widget( $args, $instance ) { * * @param array $new_instance New widget instance. * @param array $old_instance Original widget instance. - * @return array Updated widget instance. + * @return array Updated widget instance. */ public function update( $new_instance, $old_instance ) { $instance = $old_instance;