[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 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.

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