WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#30552 closed defect (bug) (fixed)

Inline Docs: Fix core DocBlock formatting and cross referencing

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.1 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description (last modified by 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.

Attachments (1)

30552.diff (67.4 KB) - added by DrewAPicture 5 years ago.
Dynamic hook docs

Download all attachments as: .zip

Change History (13)

#1 @DrewAPicture
5 years ago

  • Description modified (diff)

@DrewAPicture
5 years ago

Dynamic hook docs

#2 @DrewAPicture
5 years ago

  • Keywords has-patch added
  • Owner set to DrewAPicture
  • Status changed from new to accepted

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

#3 @DrewAPicture
5 years ago

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.

#4 @DrewAPicture
5 years ago

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

#5 @DrewAPicture
5 years ago

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.

#6 @DrewAPicture
5 years ago

In 30651:

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

See #30552.

#7 @DrewAPicture
5 years ago

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.

#8 @DrewAPicture
5 years ago

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.

#9 @DrewAPicture
5 years ago

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.

#10 @DrewAPicture
5 years ago

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.

#11 @DrewAPicture
5 years ago

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.

#12 @kpdesign
5 years ago

  • Milestone changed from Future Release to 4.1
  • Resolution set to fixed
  • Status changed from accepted to closed

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

Note: See TracTickets for help on using tickets.