From 3575a07f4b73edaf1dc14052bb99033ff5283eb8 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Wed, 11 Dec 2019 10:57:44 +0000
Subject: [PATCH] Docs: Improve documentation for `wp_dashboard_browser_nag()`
 and `dashboard_browser_nag_class()`.

Props grapplerulrich.
Fixes #48932.

git-svn-id: https://develop.svn.wordpress.org/trunk@46880 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/dashboard.php | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/src/wp-admin/includes/dashboard.php b/src/wp-admin/includes/dashboard.php
index 096cc89cde..569f078243 100644
--- a/src/wp-admin/includes/dashboard.php
+++ b/src/wp-admin/includes/dashboard.php
@@ -1471,7 +1471,7 @@ function wp_dashboard_primary() {
 }
 
 /**
- * Display the WordPress events and news feeds.
+ * Displays the WordPress events and news feeds.
  *
  * @since 3.8.0
  * @since 4.8.0 Removed popular plugins feed.
@@ -1489,7 +1489,7 @@ function wp_dashboard_primary_output( $widget_id, $feeds ) {
 }
 
 /**
- * Display file upload quota on dashboard.
+ * Displays file upload quota on dashboard.
  *
  * Runs on the {@see 'activity_box_end'} hook in wp_dashboard_right_now().
  *
@@ -1553,7 +1553,11 @@ function wp_dashboard_quota() {
 	<?php
 }
 
-// Display Browser Nag Meta Box
+/**
+ * Displays the browser update nag.
+ *
+ * @since 3.2.0
+ */
 function wp_dashboard_browser_nag() {
 	$notice   = '';
 	$response = wp_check_browser_version();
@@ -1611,10 +1615,12 @@ function wp_dashboard_browser_nag() {
 }
 
 /**
+ * Adds an additional class to the browser nag if the current version is insecure.
+ *
  * @since 3.2.0
  *
- * @param array $classes
- * @return array
+ * @param string[] $classes Array of meta box classes.
+ * @return string[] Modified array of meta box classes.
  */
 function dashboard_browser_nag_class( $classes ) {
 	$response = wp_check_browser_version();
@@ -1627,11 +1633,11 @@ function dashboard_browser_nag_class( $classes ) {
 }
 
 /**
- * Check if the user needs a browser update
+ * Checks if the user needs a browser update.
  *
  * @since 3.2.0
  *
- * @return array|bool False on failure, array of browser data on success.
+ * @return array|bool Array of browser data on success, false on failure.
  */
 function wp_check_browser_version() {
 	if ( empty( $_SERVER['HTTP_USER_AGENT'] ) ) {
@@ -1731,8 +1737,8 @@ function wp_dashboard_php_nag() {
  *
  * @since 5.1.0
  *
- * @param string[] $classes Array of metabox classes.
- * @return string[] Modified array of metabox classes.
+ * @param string[] $classes Array of meta box classes.
+ * @return string[] Modified array of meta box classes.
  */
 function dashboard_php_nag_class( $classes ) {
 	$response = wp_check_php_version();
@@ -1746,6 +1752,8 @@ function dashboard_php_nag_class( $classes ) {
 
 /**
  * Empty function usable by plugins to output empty dashboard widget (to be populated later by JS).
+ *
+ * @since 2.5.0
  */
 function wp_dashboard_empty() {}