Inline Docs: Fix core DocBlock formatting and cross referencing

[DrewAPicture]

Per the ​Formatting Guidelines in the inline docs standards for PHP in the Core Contributor Handbook most parts of DocBlocks (excluding the Summary) support some limited markdown formatting and inline @see tags for cross-referencing other functions, hooks, classes, and methods.

See #30473 for fixes related to removing invalid formatting in DocBlocks.

This will serve as a tracking ticket for commits related to formatting that DocBlock information. This formatting effort is specifically important now that we're leveraging the Code Reference for displaying the parsed core documentation.

[DrewAPicture]

Dynamic hook docs

[DrewAPicture]

30552.diff​ covers backtick-escaping inline code in DocBlocks for all dynamic hooks in core.

[DrewAPicture]

In 30647:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-admin/network/*.

Affects DocBlocks for the following hooks:

• network_admin_edit_' . $_GET['action']
• network_sites_updated_message_' . $_GET['updated']

See #30552.

[DrewAPicture]

[30648] covered wp-admin/includes/* and missed the ticket.

[DrewAPicture]

In 30649:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-admin/*.

Also includes some changes to move hook docs to directly precede hook lines. This is necessary to prevent DocBlock-matching confusion when core is parsed.

Affects DocBlocks for the following hooks:

• wp_ajax_ . $_REQUEST['action']
• wp_ajax_nopriv_ . $_REQUEST['action']
• admin_footer- . $GLOBALS['hook_suffix']
• admin_head-$hook_suffix
• admin_post_nopriv_{$action}
• admin_post_{$action}
• load- . $page_hook
• load- . $plugin_page
• load-importer- . $importer
• load- . $pagenow
• admin_action_ . $_REQUEST['action']
• async_upload_{$type}
• add_meta_boxes_ . $post_type
• {$taxonomy}_pre_edit_form
• {$taxonomy}_term_edit_form_tag
• {$taxonomy}_edit_form_fields
• {$taxonomy}_edit_form
• after-{$taxonomy}-table
• {$taxonomy}_pre_add_form
• {$taxonomy}_term_new_form_tag
• {$taxonomy}_add_form_fields
• {$taxonomy}_add_form
• media_upload_$type
• media_upload_$tab
• install_plugins_pre_$tab
• install_plugins_$tab
• install_themes_pre_{$tab}
• install_themes_{$tab}
• update-core-custom_{$action}
• update-custom_{$action}
• user_{$name}_label

See #30552.

[DrewAPicture]

In 30651:

Docs Formatting: Backtick-escape inline code for the login_form_ . $action dynamic hook in wp-login.php.

See #30552.

[DrewAPicture]

In 30652:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-includes/option.php.

Affects DocBlocks for the following hooks:

• pre_option_ . $option
• default_option_ . $option
• option_ . $option
• pre_update_option_ . $option
• update_option_{$option}
• add_option_{$option}
• delete_option_$option
• delete_transient_ . $transient
• pre_transient_ . $transient
• transient_ . $transient
• pre_set_transient_ . $transient
• set_transient_ . $transient
• pre_site_option_ . $option
• default_site_option_ . $option
• site_option_ . $option
• pre_add_site_option_ . $option
• add_site_option_{$option}
• pre_delete_site_option_ . $option
• delete_site_option_{$option}
• pre_update_site_option_ . $option
• update_site_option_{$option}
• delete_site_transient_ . $transient
• pre_site_transient_ . $transient
• site_transient_ . $transient
• pre_set_site_transient_ . $transient
• set_site_transient_ . $transient

See #30552.

[DrewAPicture]

In 30653:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-includes/post.php.

Affects DocBlocks for the following hooks:

• post_type_labels_{$post_type}
• edit_{$field}
• {$field_no_prefix}_edit_pre
• pre_{$field}
• {$field_no_prefix}_save_pre
• {$field}_pre
• $field
• save_post_{$post->post_type}
• {$old_status}_to_{$new_status}
• {$new_status}_{$post->post_type}

See #30552.

[DrewAPicture]

In 30654:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-includes/taxonomy.php.

Affects DocBlocks for the following hooks:

• get_$taxonomy
• edit_term_{$field}
• edit_{$taxonomy}_{$field}
• pre_term_{$field}
• pre_{$taxonomy}_{$field}
• term_{$field}_rss
• {$taxonomy}_{$field}_rss
• term_{$field}
• {$taxonomy}_{$field}
• delete_$taxonomy
• create_$taxonomy
• edit_$taxonomy
• edited_$taxonomy

See #30552.

[DrewAPicture]

In 30655:

Docs Formatting: Backtick-escape inline code for all dynamic hook docs in wp-includes/meta.php.

Affects DocBlocks for the following hooks:

• add_{$meta_type}_metadata
• add_{$meta_type}_meta
• added_{$meta_type}_meta
• update_{$meta_type}_metadata
• update_{$meta_type}_meta
• updated_{$meta_type}_meta
• delete_{$meta_type}_metadata
• delete_{$meta_type}_meta
• deleted_{$meta_type}_meta
• get_{$meta_type}_metadata
• delete_{$meta_type}meta
• deleted_{$meta_type}meta
• sanitize_{$meta_type}_meta_{$meta_key}

See #30552.

[DrewAPicture]

In 30656:

Docs Formatting: Backtick-escape inline code for all remaining dynamic hook docs in wp-includes/*.

Affects DocBlocks for the following hooks:

• auth_post_meta_{$meta_key}
• term_links-$taxonomy
• customize_render_control_ . $this->id
• customize_render_panel_{$this->id}
• customize_render_section_{$this->id}
• customize_preview_{$this->id}
• customize_save_ . $this->id_data[ 'base' ]
• customize_update_ . $this->type
• customize_value_ . $this->id_data[ 'base' ]
• customize_sanitize_js_{$this->id}
• comment_form_field_{$name}
• comment_{$old_status}_to_{$new_status}
• comment_{$new_status}_{$comment->comment_type}
• extra_{$context}_headers
• get_template_part_{$slug}
• get_the_generator_{$type}
• get_{$adjacent}_post_join
• get_{$adjacent}_post_where
• get_{$adjacent}_post_sort
• {$adjacent}_post_rel_link
• {$adjacent}_post_link
• {$adjacent}_image_link
• blog_option_{$option}
• $permastructname . _rewrite_rules
• {$type}_template
• theme_mod_{$name}
• pre_set_theme_mod_$name
• current_theme_supports-{$feature}
• get_user_option_{$option}
• edit_user_{$field}
• pre_user_{$field}
• user_{$field}

See #30552.

[kpdesign]

Closing as fixed. We'll open a new ticket for 4.2.