Hooks Docs: wp-admin/options-reading.php

[siobhyb]

First pass at inline docs for wp-admin/options-reading.php.

[DrewAPicture]

Hi Siobhan, thanks for the patch :)

So, this hook is kind of interesting because it mostly serves to provide backward-compatibility for adding additional-level privacy setting to the fieldset that used to live in the now-defunct options-privacy.php See #16416 for when those settings screens were consolidated.

And if you look at the current code, you'll notice that the section of the table that the action runs in is only displayed if that hook has a callback hooked to it.

The logic behind it is explained pretty well in the commit message for [21838]:

When blog_public only has two values (as judged by whether the blog_privacy_selector action is used), convert from radio buttons to a checkbox, and rename from 'Site Visibility' to a more specific 'Search Engine Visibility'.

The reason I bring this up is that we should find a way to succinctly explain this behavior in the hook doc, probably using a long (but not too long!) description.

Also, in the future, could you please remember to generate patches from the WordPress root? :)

[siobhyb]

Hi Drew. I've attached the updated patch with the long description added. I borrowed heavily from the original commit message!

This action is required in order to add additional values to the privacy options form. When called, the form's default radio buttons are converted to check boxes, and the 'Site Visibility' heading is changed to the more specific 'Search Engine Visibility.'

I suspect it may still require some editing, let me know. Thanks for your help. :)

[siobhyb]

Pass 2 at wp-admin/option-reading.php

[siobhyb]

Pass 2 at wp-admin/option-reading.php

[siobhyb]

Sorry, had some formatting issues. "options-reading.patch​" is the latest.

[siobhyb]

wp-admin/option-reading.php

[DrewAPicture]

Third pass

[DrewAPicture]

Looking at the long description in options-reading.patch​, it's actually backwards. The default behavior is to show a checkbox, and if hooked, the action flips the form to radio buttons, opening the door for additional options to be added.

I reworked the language in 25430.diff​. What do you think?

[DrewAPicture]

s/This action/Hooking to this action

[DrewAPicture]

In 25717:

Inline documentation for wp-admin/options-reading.php.

Props siobhyb for the initial patch.
Fixes #25430.

[siobhyb]

Much better, thanks for improving.