[wp-trac] [WordPress Trac] #57337: Docs: WP Theme class reference properties don't match code

[WordPress Trac]

#57337: Docs: WP Theme class reference properties don't match code
---------------------------+------------------------------
 Reporter:  bertvandepoel  |       Owner:  (none)
     Type:  defect (bug)   |      Status:  new
 Priority:  normal         |   Milestone:  Awaiting Review
Component:  Themes         |     Version:
 Severity:  normal         |  Resolution:
 Keywords:                 |     Focuses:  docs
---------------------------+------------------------------

Comment (by 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.
 }}}
 [https://developer.wordpress.org/reference/classes/wp_theme/get/#parameters
 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?

 {{{#!diff
         /**
          * __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:
 {{{#!diff
  * 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?

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/57337#comment:4>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform