Twenty Eleven: Improve PHP DocBlock compliance with WordPress Documentation Standards

[huzaifaalmesbah]

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

[noruzzaman]

Thanks for detailing the gaps. I’ve reviewed the code in inc/theme-options.php and inc/widgets.php and can confirm the issue is valid. Several functions are missing @return/@param tags.

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()

Files modified:

• inc/theme-options.php: Updated 9 function DocBlocks
• inc/widgets.php: Enhanced widget update() method documentation

Fixes https://core.trac.wordpress.org/ticket/64211

Thanks for the detailed review and version history notes @sabernhardt I’ve updated the @since tags accordingly and reviewed your suggestions for Twenty_Eleven_Ephemera_Widget::update(). Really appreciate your guidance!

[ravichudasama01]

I reviewed inc/widgets.php and found that the @param tags are now in place, but several methods are still missing @return tags. Here’s the list for reference:

widget() → should have @return void

update() → should have @return array

[westonruter]

@ravichudasama01 For the widget() method: Core doesn't typically use @return void, except in third party libraries. The exception to this is when the function can return void or a non-void value, for example do_enclose() has @return void|false. I think core should update any such uses of void to return null instead, in any case.

As for the update method, I see the phpdoc being added? See ​file in PR.

[westonruter]

In 61309:

Twenty Eleven: Improve PHP docblocks with corrected descriptions, missing/corrected tags, and specific types.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10482

Props huzaifaalmesbah, dhruvang21, juanfra, sabernhardt, noruzzaman, ravichudasama01, westonruter.
See #64224.
Fixes #64211.