Argument type does not match: theme.php

[subrataemfluence]

In the function doc of get_theme_root_uri(), the argument types of $stylesheet_or_template and $theme_root do not match. Default values of arguments are boolean but in function doc they are stated as strings.

File name: wp-admin/theme.php
Function: get_theme_root_uri

<?php
/**
 * Retrieve URI for themes directory.
 *
 * Does not have trailing slash.
 *
 * @since 1.5.0
 *
 * @global array $wp_theme_directories
 *
 * @param string $stylesheet_or_template Optional. The stylesheet or template name of the theme.
 *                                       Default is to leverage the main theme root.
 * @param string $theme_root             Optional. The theme root for which calculations will be based, preventing
 *                                       the need for a get_raw_theme_root() call.
 * @return string Themes URI.
 */
function get_theme_root_uri( $stylesheet_or_template = false, $theme_root = false ) {
   ...
}

Can we re-write the parameter descriptions in the following way?

<?php
 * @param string | bool $stylesheet_or_template Optional. The stylesheet or template name of the theme.
 *                                       Default is to leverage the main theme root. Default value false.
 * @param string | bool $theme_root             Optional. The theme root for which calculations will be based, preventing
 *                                       the need for a get_raw_theme_root() call. Default value false.

since we are checking for boolean values of these two parameters inside the function body like:

<?php
if ( $stylesheet_or_template && ! $theme_root ) {
   $theme_root = get_raw_theme_root( $stylesheet_or_template );
}

if ( $stylesheet_or_template && $theme_root ) {
   ...
}

and on the other hand we are passing string values to theses parameters when calling this function like this:

<?php
$this->theme_root_uri = get_theme_root_uri( $this->stylesheet, $this->theme_root );

[williampatton]

To me this looks like a good improvement to the documentation that is better at showing how the function works at a glance. The spaces look off to me though and I don't think they fit within coding styles. There should be no spaces between the types like string|bool.

Also could we maybe go the other way around like bool|string since the Boolean is the default?

[subrataemfluence]

@williampatton Thank you for accepting the patch. I am uploading a refreshed patch with changes made according to your suggestion. Please let me know if this works.

[subrataemfluence]

Updated patch

[williampatton]

Hey @subrataemfluence, thank you for submitting the original patch and flagging the documentation change that is needed. The newly uploaded patch suits me fine :)

I plan to try get this into 5.3 release and between then and now I will get some more eyes on it if anyone else wanted to give some input before it was added.

[williampatton]

This ticket is ready for commit and should be an easy drop-in. It contains no code changes, just a small inline docs correction.

[garrett-eclipse]

Minor Refresh to update verbiage to "Default value false, to use the main theme root." and fix indent on following lines of docblock

[garrett-eclipse]

In patch 44397.3.diff I've made a minor update to account for the Slack discussion found here;
​https://wordpress.slack.com/archives/C02RQBWTW/p1566933586265600

*Also updated this to bug as the docblock was incorrect and this fixes it.

[williampatton]

The patch in this one at 44397.3.diff looks good to me and applies cleanly still on my end.

This is good for commit

[whyisjake]

In 46327:

Themes: Docblock cleanup for get_theme_root_uri()

In the function docblock of get_theme_root_uri(), the argument types of $stylesheet_or_template and $theme_root do not match. Default values of arguments are boolean but in function doc they are stated as strings.

Props subrataemfluence, williampatton, garrett-eclipse.
Fixes #44397.

[SergeyBiryukov]

Given that these parameters are still documented as strings in get_theme_root(), get_raw_theme_root() and the theme_root_uri filter, and are not explicitly checked for false, I think a more consistent fix would be to actually bring the default values in line with the documentation.

[SergeyBiryukov]

In 46392:

Themes: Bring default values for get_theme_root(), get_theme_root_uri(), wp_get_theme(), and wp_customize_url() in line with the documentation.

Reverts [46327].

Fixes #44397.