Docs: WP Theme class reference properties don't match code

[bertvandepoel]

I was developing a plugin based on the information on ​https://developer.wordpress.org/reference/classes/wp_theme/ . This page implies that I should be able to get the theme author using the Author property and the URI of the Author's website using the AuthorURI property. However, in reality the AuthorURI property is always NULL and the Author property contains the author embedded inside an <a> tag with the AuthorURI. The docs should more clearly reflect this, and ideally mention a way to get the bare Author and URI (I ended up not finding a way to even do this, so I'm parsing the HTML now, really silly).

[costdev]

Hi @bertvandepoel, thanks for opening this ticket!

You should be able to use:

wp_get_theme()->get( 'Author' )
or
wp_get_theme()->display( 'Author', false )
( $markup = false )

The documentation for __get() magic method is:

__get() magic method for properties
formerly returned by current_theme_info()

current_theme_info() was deprecated in WordPress 3.4.0, so this magic method is just here for BC.

I'm not sure a change to the documentation is necessary here, as ::get() and ::display() are the appropriate methods to use.

[bertvandepoel]

Thank you for explaining. I would argue that documentation could be improved to pass this information more clearly.

The beginning of the docs state "You shouldn’t alter the properties directly, but instead use the methods to interact with them. For complete list of methods and properties, refer the source code.". For me this implied that I can and should access properties directly using ->PropertyName but shouldn't assign values to them.

The descriptions for both get() and get() don't really explain what they do. get() talks about compatibility with a function I had never heard of and has been deprecated for a really long time. get() talks about the theme header, but that term isn't explained, nor what it contains.
I also simply didn't look at all the function in detail, since the documentation implied to me that reading properties was possible.

I would at least adapt the text under "Methods and Properties" to no longer say "alter" but something more general, since you also should be reading properties directly based on what you and people on IRC have said. Perhaps "access" would be a better word. I would also suggest mentioning somewhere that get() is the way to go, instead of making it sound like "good luck, go read the source code", which is what it says right now.

[costdev]

The get() method provides examples of theme headers for the $header parameter:

* @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.

​Ref

I'm not sure if "shouldn't access" is correct. Getting values via __get() isn't a problem as such. It's just that the value it returns for a given property/header is based on what was previously returned by current_theme_info(). For Author and Description, this returns WP_Theme::display(), with the $markup parameter defaulting to true.

I think potential docs changes may be best focused on the __get() method. What about this?

        /**
         * __get() magic method for properties formerly returned by current_theme_info()
         *
+        * For 'Author' and 'Description', this will return values with markup.
+        * To get the raw, unformatted values, use the get() method.
+        * To get the values for display, use the display() method.
+        *
         * @since 3.4.0
         *
         * @param string $offset Property to get.
         * @return mixed Property value.
         */

This is based on this part of the WP_Theme::get() docblock:

 * The header is sanitized, but is not translated, and is not marked up for display.
 * To get a theme header for display, use the display() method.

I changed "a theme header" to "the values" to avoid confusion as the __get() docblock mentions "properties", not "theme headers".

What do you think?

[bertvandepoel]

I'm not quite sure where this would change things on ​https://developer.wordpress.org/reference/classes/wp_theme/ , which has been the main source of my confusion. Could you perhaps explain to me? Are those pages generated based on the docstrings? If so, I'm unaware of that.

[costdev]

Making the change I suggested here would change ​this page.

__get() magic method for properties formerly returned by current_theme_info()

Would become:

__get() magic method for properties formerly returned by current_theme_info()

For 'Author' and 'Description', this will return values with markup.
To get the raw, unformatted values, use the get() method.
To get the values for display, use the display() method.

Regarding ​this page, I don't see any reference to this part in the codebase:

You shouldn’t alter the properties directly, but instead use the methods to interact
with them. For complete list of methods and properties, refer the source code.

So this part might be edited another way. @SergeyBiryukov, do you have any idea about this, and do you have any thoughts on this ticket?