docblock for theme_get_setting is confusing [#716554]

The current docblock for theme_get_setting includes notes for core developers if they update the module. That should be a code comment, not a part of the "how do I use this function" documentation.

Comment	File	Size	Author
#5	theme-get-setting-docblock-716554-5.patch	2.67 KB	JohnAlbin
#5
#3	theme-get-setting-docblock-716554-3.patch	2.66 KB	JohnAlbin
#3
#1	theme-get-setting-docblock-716554-1.patch	1.91 KB	JohnAlbin
#1

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

JohnAlbin

he/they/他

English

Taipei, Taiwan

CreditAttribution: JohnAlbin commented 17 February 2010 at 03:52

Status:

Active

» Needs review

File	Size
theme-get-setting-docblock-716554-1.patch	1.91 KB

This patch makes minor tweaks to the theme_get_setting comments and moves this entire paragraph to a code comment:

The default values for each setting is defined in this function. To add new
settings, add their default values here, and then add form elements to
system_theme_settings() in system.admin.inc.

Comment #2

Nick Lewis CreditAttribution: Nick Lewis commented 17 February 2010 at 05:22

I think the next paragraph should simply read "The site-wide defaults are used unless overridden by theme specific settings, or settings declared in theme's .info file." and then its good to go.

Comment #3

JohnAlbin

he/they/他

English

Taipei, Taiwan

CreditAttribution: JohnAlbin commented 17 February 2010 at 06:16

File	Size
theme-get-setting-docblock-716554-3.patch	2.66 KB

What Nick says makes it clear that my changes are insufficient to clarify what the hell is going on. I know the code very well, but didn't update the docs much when I re-wrote the code.

Per the conversation I had with Nick in IRC, I'm replacing all the refs to "site-wide settigns" with "global settings" since that's the text that is used on the admin/appearance/settings form.

Here's a complete re-write of the docs and some of the comments.