[wp-trac] [WordPress Trac] #64211: Twenty Eleven: Improve PHP DocBlock compliance with WordPress Documentation Standards

[WordPress Trac]

#64211: Twenty Eleven: Improve PHP DocBlock compliance with WordPress Documentation
Standards
-----------------------------+-----------------------------
 Reporter:  huzaifaalmesbah  |      Owner:  (none)
     Type:  enhancement      |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  Bundled Theme    |    Version:
 Severity:  normal           |   Keywords:
  Focuses:  docs             |
-----------------------------+-----------------------------
 The Twenty Eleven theme’s PHP DocBlocks need improvements to fully comply
 with the WordPress PHP Documentation Standards as outlined in the
 Developer Handbook.

 == Changes Needed ==

 1. '''Function summaries''' – Update to use third-person singular verbs
 consistently
 2. '''Missing @return tags''' – Add return type documentation where
 missing
 3. '''Missing @param tags''' – Complete parameter documentation for widget
 methods
 4. '''Sentence structure''' – Ensure all descriptions end with proper
 punctuation

 == Files to Update ==

 * `src/wp-content/themes/twentyeleven/inc/theme-options.php`
 * `src/wp-content/themes/twentyeleven/inc/widgets.php`

 == Specific Improvements ==

 === inc/theme-options.php ===

 * `twentyeleven_admin_enqueue_scripts()` – Update summary to use third-
 person singular verb
 * `twentyeleven_theme_options_add_page()` – Improve grammar in summary
 * `twentyeleven_theme_options_help()` – Add missing DocBlock with `@since`
 tag
 * `twentyeleven_color_schemes()` – Add `@return` tag
 * `twentyeleven_layouts()` – Add `@return` tag
 * `twentyeleven_get_theme_options()` – Add `@return` tag
 * `twentyeleven_theme_options_validate()` – Add `@return` tag
 * `twentyeleven_layout_classes()` – Add `@return` tag
 * `twentyeleven_customize_register()` – Fix sentence punctuation

 === inc/widgets.php ===

 * `Twenty_Eleven_Ephemera_Widget::update()` – Add complete `@param` and
 `@return` documentation

 == References ==

 * https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php

 == Testing ==

 * Verify theme functionality remains unchanged
 * Confirm DocBlocks render correctly in Code Reference
 * Check PHPDoc parsing compatibility

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64211>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform