From 506780a9154b31717f71526765fb1f572a9cff68 Mon Sep 17 00:00:00 2001
From: Jignesh Bhavani <jigzbhavani@gmail.com>
Date: Fri, 31 Jul 2026 18:28:47 +0530
Subject: [PATCH] Bundled Themes: Document the parameters of five template
 functions.

Five functions in Twenty Nineteen and Twenty Twelve accept arguments but carry no `@param` tag at all.

* Twenty Nineteen: `twentynineteen_get_user_avatar_markup()`, `twentynineteen_discussion_avatars_list()`, and `twentynineteen_comment_form()` had a description and nothing else. The first also returns markup, so it gains a `@return`.
* Twenty Twelve: `twentytwelve_page_menu_args()` and `twentytwelve_content_nav()`, in a file that otherwise documents its parameters throughout.

The types come from the call sites. `twentynineteen_comment_form()` is called with `'asc'`, `'desc'`, and `true`, so it is documented as `bool|string`. The authors passed to `twentynineteen_discussion_avatars_list()` are built in `twentynineteen_get_discussion_data()` as a user ID, or the author email where there is no account.

No `@since` tags are added. The Twenty Nineteen file does not use them on functions, and the two Twenty Twelve functions already have them.

No functional change.

See #64896.
---
 .../themes/twentynineteen/inc/template-tags.php      | 12 ++++++++++++
 src/wp-content/themes/twentytwelve/functions.php     |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/src/wp-content/themes/twentynineteen/inc/template-tags.php b/src/wp-content/themes/twentynineteen/inc/template-tags.php
index 63e9f78e1b505..95d63089f0376 100644
--- a/src/wp-content/themes/twentynineteen/inc/template-tags.php
+++ b/src/wp-content/themes/twentynineteen/inc/template-tags.php
@@ -170,6 +170,11 @@ function twentynineteen_post_thumbnail() {
 if ( ! function_exists( 'twentynineteen_get_user_avatar_markup' ) ) :
 	/**
 	 * Returns the HTML markup to generate a user avatar.
+	 *
+	 * @param mixed $id_or_email Optional. The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
+	 *                           user email, WP_User object, WP_Post object, or WP_Comment object.
+	 *                           Default null, which uses the current user ID.
+	 * @return string The avatar markup.
 	 */
 	function twentynineteen_get_user_avatar_markup( $id_or_email = null ) {
 
@@ -184,6 +189,9 @@ function twentynineteen_get_user_avatar_markup( $id_or_email = null ) {
 if ( ! function_exists( 'twentynineteen_discussion_avatars_list' ) ) :
 	/**
 	 * Displays a list of avatars involved in a discussion for a given post.
+	 *
+	 * @param array $comment_authors Comment authors to display avatars for. Each entry is a user ID,
+	 *                               or an email address for authors without an account.
 	 */
 	function twentynineteen_discussion_avatars_list( $comment_authors ) {
 		if ( empty( $comment_authors ) ) {
@@ -203,6 +211,10 @@ function twentynineteen_discussion_avatars_list( $comment_authors ) {
 if ( ! function_exists( 'twentynineteen_comment_form' ) ) :
 	/**
 	 * Displays the comment form.
+	 *
+	 * @param bool|string $order Whether to display the form. Accepts 'asc' or 'desc' to display it only
+	 *                           when the value matches the 'comment_order' option, or true to always
+	 *                           display it.
 	 */
 	function twentynineteen_comment_form( $order ) {
 		if ( true === $order || strtolower( $order ) === strtolower( get_option( 'comment_order', 'asc' ) ) ) {
diff --git a/src/wp-content/themes/twentytwelve/functions.php b/src/wp-content/themes/twentytwelve/functions.php
index 2d6094e3f3e56..ef56a9fa3cfae 100644
--- a/src/wp-content/themes/twentytwelve/functions.php
+++ b/src/wp-content/themes/twentytwelve/functions.php
@@ -344,6 +344,10 @@ function twentytwelve_wp_title( $title, $sep ) {
  * Makes our wp_nav_menu() fallback -- wp_page_menu() -- show a home link.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @param array $args An array of page menu arguments. See wp_page_menu() for information
+ *                    on accepted arguments.
+ * @return array Filtered page menu arguments.
  */
 function twentytwelve_page_menu_args( $args ) {
 	if ( ! isset( $args['show_home'] ) ) {
@@ -422,6 +426,8 @@ function wp_get_list_item_separator() {
 	 * @since Twenty Twelve 1.0
 	 *
 	 * @global WP_Query $wp_query WordPress Query object.
+	 *
+	 * @param string $html_id The HTML id attribute for the navigation element.
 	 */
 	function twentytwelve_content_nav( $html_id ) {
 		global $wp_query;