Docs: Improve documentation for a few functions per the documentation standards.

This affects:
* `checked()`
* `selected()`
* `disabled()`
* `wp_readonly()`
* `readonly()`
* `__checked_selected_helper()`

Follow-up to [143], [560], [9053], [10662], [13658], [41728], [51586].

See #53399.

git-svn-id: https://develop.svn.wordpress.org/trunk@51592 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

src/wp-includes/general-template.php

@@ -4763,14 +4763,16 @@ function get_the_generator( $type = '' ) {
 /**
  * Outputs the HTML checked attribute.
  *
- * Compares the first two arguments and if identical marks as checked
+ * Compares the first two arguments and if identical marks as checked.
  *
  * @since 1.0.0
  *
- * @param mixed $checked One of the values to compare
- * @param mixed $current (true) The other value to compare if not just true
- * @param bool  $echo    Whether to echo or just return the string
- * @return string HTML attribute or empty string
+ * @param mixed $checked One of the values to compare.
+ * @param mixed $current Optional. The other value to compare if not just true.
+ *                       Default true.
+ * @param bool  $echo    Optional. Whether to echo or just return the string.
+ *                       Default true.
+ * @return string HTML attribute or empty string.
  */
 function checked( $checked, $current = true, $echo = true ) {
 	return __checked_selected_helper( $checked, $current, $echo, 'checked' );
@@ -4779,14 +4781,16 @@ function checked( $checked, $current = true, $echo = true ) {
 /**
  * Outputs the HTML selected attribute.
  *
- * Compares the first two arguments and if identical marks as selected
+ * Compares the first two arguments and if identical marks as selected.
  *
  * @since 1.0.0
  *
- * @param mixed $selected One of the values to compare
- * @param mixed $current  (true) The other value to compare if not just true
- * @param bool  $echo     Whether to echo or just return the string
- * @return string HTML attribute or empty string
+ * @param mixed $selected One of the values to compare.
+ * @param mixed $current  Optional. The other value to compare if not just true.
+ *                        Default true.
+ * @param bool  $echo     Optional. Whether to echo or just return the string.
+ *                        Default true.
+ * @return string HTML attribute or empty string.
  */
 function selected( $selected, $current = true, $echo = true ) {
 	return __checked_selected_helper( $selected, $current, $echo, 'selected' );
@@ -4795,14 +4799,16 @@ function selected( $selected, $current = true, $echo = true ) {
 /**
  * Outputs the HTML disabled attribute.
  *
- * Compares the first two arguments and if identical marks as disabled
+ * Compares the first two arguments and if identical marks as disabled.
  *
  * @since 3.0.0
  *
- * @param mixed $disabled One of the values to compare
- * @param mixed $current  (true) The other value to compare if not just true
- * @param bool  $echo     Whether to echo or just return the string
- * @return string HTML attribute or empty string
+ * @param mixed $disabled One of the values to compare.
+ * @param mixed $current  Optional. The other value to compare if not just true.
+ *                        Default true.
+ * @param bool  $echo     Optional. Whether to echo or just return the string.
+ *                        Default true.
+ * @return string HTML attribute or empty string.
  */
 function disabled( $disabled, $current = true, $echo = true ) {
 	return __checked_selected_helper( $disabled, $current, $echo, 'disabled' );
@@ -4811,14 +4817,16 @@ function disabled( $disabled, $current = true, $echo = true ) {
 /**
  * Outputs the HTML readonly attribute.
  *
- * Compares the first two arguments and if identical marks as readonly
+ * Compares the first two arguments and if identical marks as readonly.
  *
  * @since 5.9.0
  *
- * @param mixed $readonly One of the values to compare
- * @param mixed $current  (true) The other value to compare if not just true
- * @param bool  $echo     Whether to echo or just return the string
- * @return string HTML attribute or empty string
+ * @param mixed $readonly One of the values to compare.
+ * @param mixed $current  Optional. The other value to compare if not just true.
+ *                        Default true.
+ * @param bool  $echo     Optional. Whether to echo or just return the string.
+ *                        Default true.
+ * @return string HTML attribute or empty string.
  */
 function wp_readonly( $readonly, $current = true, $echo = true ) {
 	return __checked_selected_helper( $readonly, $current, $echo, 'readonly' );
@@ -4837,16 +4845,16 @@ function wp_readonly( $readonly, $current = true, $echo = true ) {
 /**
  * Private helper function for checked, selected, disabled and readonly.
  *
- * Compares the first two arguments and if identical marks as $type
+ * Compares the first two arguments and if identical marks as `$type`.
  *
  * @since 2.8.0
  * @access private
  *
- * @param mixed  $helper  One of the values to compare
- * @param mixed  $current (true) The other value to compare if not just true
- * @param bool   $echo    Whether to echo or just return the string
- * @param string $type    The type of checked|selected|disabled|readonly we are doing
- * @return string HTML attribute or empty string
+ * @param mixed  $helper  One of the values to compare.
+ * @param mixed  $current The other value to compare if not just true.
+ * @param bool   $echo    Whether to echo or just return the string.
+ * @param string $type    The type of checked|selected|disabled|readonly we are doing.
+ * @return string HTML attribute or empty string.
  */
 function __checked_selected_helper( $helper, $current, $echo, $type ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore,PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
 	if ( (string) $helper === (string) $current ) {

src/wp-includes/php-compat/readonly.php

@@ -15,7 +15,7 @@
 /**
  * Outputs the HTML readonly attribute.
  *
- * Compares the first two arguments and if identical marks as readonly
+ * Compares the first two arguments and if identical marks as readonly.
  *
  * This function is deprecated, and cannot be used on PHP >= 8.1.
  *
@@ -24,10 +24,12 @@
  *
  * @see wp_readonly()
  *
- * @param mixed $readonly One of the values to compare
- * @param mixed $current  (true) The other value to compare if not just true
- * @param bool  $echo     Whether to echo or just return the string
- * @return string HTML attribute or empty string
+ * @param mixed $readonly One of the values to compare.
+ * @param mixed $current  Optional. The other value to compare if not just true.
+ *                        Default true.
+ * @param bool  $echo     Optional. Whether to echo or just return the string.
+ *                        Default true.
+ * @return string HTML attribute or empty string.
  */
 function readonly( $readonly, $current = true, $echo = true ) {
 	_deprecated_function( __FUNCTION__, '5.9.0', 'wp_readonly()' );