WordPress.org
Get WordPress

Make WordPress Core

Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#30473 closed defect (bug) (fixed)

Inline Docs: Remove invalid markup from DocBlocks

Reported by: drewapicture's profile DrewAPicture Owned by: rarst's profile rarst
Milestone: 4.1 Priority: high
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

Background: Core documentation has been parsed into the new Code Reference for a couple of releases now. As such, there are quite a few cases where HTML markup located in various places in DocBlocks is wreaking havoc on how that content displayed via WordPress.

The primary goal of this ticket is to fix as many of these cases as possible prior to the 4.1 release when the code base be parsed into the Code Reference for the new version.

Attachments (2)

30473.diff​ (54.8 KB) - added by DrewAPicture 10 years ago.
props rarst
30473.2.diff​ (1.5 KB) - added by DrewAPicture 10 years ago.

Download all attachments as: .zip

Change History (27)

@DrewAPicture
10 years ago

props rarst

#1 @DrewAPicture
10 years ago

  • Keywords has-patch added
  • Owner set to rarst
  • Status changed from new to assigned

#2 @DrewAPicture
10 years ago

In 30535:

Remove HTML <head> tags from DocBlock summaries in wp-admin/admin-header.php.

Also better-specify the $hook_suffix value in the admin_head-$hook_suffix hook docs per hook documentation precedent.

Props rarst for the initial patch.
See #30473

#3 @DrewAPicture
10 years ago

In 30536:

Ensure inline code is markdown-escaped as such, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Two arguments in _walk_bookmarks()
  • A code snippet in the class header for WP_Roles
  • A code snippet in the class header for WP_HTTP_Proxy
  • Inline code fixes in the summary and a parameter description for WP_oEmbed::discover()
  • An argument description in _WP_Editors::parse_settings()
  • Inline code fixes in the summary and a parameter description the embed_oembed_discover hook.

Props rarst.
See #30473.

#4 @DrewAPicture
10 years ago

In 30537:

Ensure inline code is markdown-escaped as such, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Backtick-escapes a <link> tag in a parameter description for the embed_oembed_discover hook
  • Inline code fixes in the summary and return description for WP_List_Table::get_table_classes()
  • Removes HTML markup from the summary for WP_List_Table::display_rows_or_placeholder()
  • Backtick-escapes a <tr> tag in a parameter description for WP_Users_List_Table::single_row()
  • Converts non-DocBlocks into multi-line comments in WP_Dependencies::do_items()
  • Removes HTML markup from the summary for the comment_form_top hook.
  • Inline code and snippet fixes in the description for wp_get_schedules()

Props rarst for the initial patch.
See #30473.

#5 @DrewAPicture
10 years ago

In 30538:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Remove HTML tag from parameter description in comment_form()
  • Remove HTML tag from a summary for the comment_form_top hook
  • Markdown-indent a code snippet in the description for get_linkobjectsbyname()
  • Markdown-indent a code snippet and format an unordered list in the description for get_linkobjects()
  • Backtick-escape some inline code in the description for clean_pre()
  • Remove HTML tag from the summary for the rss_tag_pre hook
  • Various formatting fixes in the descriptions for get_filesystem_method() and request_filesystem_credentials()

Props rarst for the initial patch.
See #30473.

#6 @DrewAPicture
10 years ago

In 30539:

Ensure the DocBlock directly precedes the hook line for the post_edit_form_tag action in wp-admin/edit-form-advanced.php.

This fixes the parser getting confused about which DocBlock belongs to which hook or function in this file.

See #30473.

#7 @DrewAPicture
10 years ago

In 30540:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements in wp-includes/formatting.php:

  • Markdown-indent code snippets in the description for wptexturize()
  • Backtick-escape inline code in a parameter description for _wptexturize_pushpop_element()
  • Backtick-escape inline code in the description for shortcode_unautop()
  • Backtick-escape HTML tags in the description for convert_chars()
  • Markdown-indent a code snippet in the description for _split_str_by_whitespace()
  • Backtick-escape an <img> tag in the description for translate_smiley()
  • Add markdown formatting to the description for links_add_target()
  • Backtick-escape HTML tags in the description for wp_strip_all_tags()

Props rarst.
See #30473.

#8 @DrewAPicture
10 years ago

In 30541:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Markdown-indent a code snippet in the description for _deprecated_argument()
  • Markdown-indent a code snippet in the description for wp_localize_script()
  • Backtick-escape HTML tags in two parameter descriptions for wp_register()
  • Various DocBlock formatting in the description for get_bloginfo()
  • Remove HTML tag from the summary for _wp_render_title_tag()
  • Backtick-escape a HTML tag in the description for get_archives_link()
  • Markdown-indent a code snippet in the description for wp_admin_css_color()
  • Markdown-indent a code snippet in the description for the welcome_panel hook

Props rarst.
See #30473.

#9 @DrewAPicture
10 years ago

In 30542:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Markdown-indent a code snippet in the file header for wp-admin/install-helper.php
  • Add markdown formatting and two inline @see tags to the description for translate()
  • Markdown-indent a code snippet in the description for _n_noop()
  • Remove HTML tags from the summary for get_media_embedded_in_content()
  • Remove an HTML tag from the summary for wpview_media_sandbox_styles()

Props rarst.
See #30473.

#10 @DrewAPicture
10 years ago

In 30543:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Backtick-escape an HTML tag in the description for the media_upload_mime_type_links() hook
  • Backtick-escape inline code in the description for wp_get_active_network_plugins()
  • Remove HTML tags from the summaries for the nav_menu_css_class, nav_menu_item_id, and nav_menu_link_attributes hooks
  • Backtick-escape HTML tags, add inline @see tags to parameter descriptions for the nav_menu_css_class, nav_menu_item_id, and nav_menu_link_attributes hooks

Props rarst.
See #30473.

#11 @DrewAPicture
10 years ago

In 30544:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Markdown-indent a code snippet in the description for wp_salt()
  • Backtick-escape inline code in the return description for get_avatar()
  • Various markdown formatting in the description for add_filter()
  • Markdown-indent a code snippet in the description for apply_filters()
  • Backtick-escape inline code in the @see description for apply_filters_ref_array()
  • Backtick-escape inline code in the description for do_action()
  • Backtick-escape variables in the parameter and return descriptions for do_action_ref_array()
  • Various markdown formatting in the description for get_plugin_data()

Props rarst.
See #30473.

#12 @DrewAPicture
10 years ago

In 30545:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Backtick-escape HTML tags in several argument descriptions for wp_link_pages()
  • Remove an HTML tag from the summary for prepend_attachment()
  • Backtick-escape inline code in the description for get_extended()
  • Backtick-escape inline code in the description for get_post_type_labels()
  • Various markdown formatting in the description for add_rewrite_endpoint()
  • Markdown-indent a code snippet in the file header for wp-includes/shortcodes.php
  • Markdown-indent code snippets in the description for `add_shortcode()

Props rarst.
See #30473.

#13 @DrewAPicture
10 years ago

In 30546:

Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:

  • Backtick-escape code snippets in the description for get_object_taxonomies()
  • Backtick-escape inline code in a markdown-formatted unordered list in the description for get_taxonomy_labels()
  • Remove an HTML tag from the summary for the Walker_Category_Checklist class
  • Remove an HTML tag from the summary for wp_category_checklist(), various formatting
  • Remove an HTML tag from the summary for wp_terms_checklist()
  • Backtick-escape an HTML tag in the description for wp_popular_terms_checklist()
  • Remove HTML tags from the summaries for page_template_dropdown(), parent_dropdown(), and wp_dropdown_roles()
  • Backtick-escape HTML tags in a parameter description for add_settings_error()
  • Various formatting in the description and summary for settings_errors()
  • Markdown-indent code snippets in the descriptions for wpdb::prepare(), wpdb::insert(), wpdb::replace(), wpdb::update(), and wpdb::delete()
  • Backtick-escape an HTML tag in a parameter description for login_header()
  • Remove HTML tags from the summaries for the lostpassword_form and signup_header hooks

Props rarst.
See #30473.

#14 @DrewAPicture
10 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

Let's call this fixed for 4.1. Nice work Rarst!

#15 follow-up: @GaryJ
10 years ago

It's good work, but there's still some inconsistencies. Even in r30543 alone, there's instances of:

  • li element
  • 'a' element
  • <a>element.

The top one doesn't have any delimiter (wrong), and the second does, but it isn't backticks so the end result isn't parsed marked up as <code>. The last one is the most correct - the doc standard needs to clarify if the instance of a tag needs to have angle brackets within the backticks or not, and then apply that consistently.

#16 in reply to: ↑ 15 ; follow-up: @Rarst
10 years ago

Replying to GaryJ:

The top one doesn't have any delimiter (wrong), and the second does, but it isn't backticks so the end result isn't parsed marked up as <code>. The last one is the most correct - the doc standard needs to clarify if the instance of a tag needs to have angle brackets within the backticks or not, and then apply that consistently.

  • First one is not wrong, it's what ​formatting guidelines currently say to do in summaries.
  • Second one is tad special case since it would be too easily confused as English article otherwise.
  • The third case is used in descriptions, which (unlike summaries) currently allow markdown. Please point out if you see otherwise anywhere.

#17 in reply to: ↑ 16 @GaryJ
10 years ago

Bad wording on my part - I didn't mean your patch was out and out wrong - just that the formatting guidelines in the current docs standard has some unfortunate inconsistencies. The fact that the special case example 2 exists highlights that either 1 should match, or 2 should be changed to:

  • anchor element

and that point 1 may therefore be better read as:

  • list item element

The formatting guidelines is ambiguous as to how abbreviated element names should be handled as it only covers the trivial link example. How the consistency should resolved is up to the Docs team to decide, hence the reason I didn't write a patch.

#18 @DrewAPicture
10 years ago

In 30618:

4.1 Docs Audit: Spell out HTML element names in DocBlock summaries for the nav_menu_css_class, nav_menu_item_id, and nav_menu_link_attributes filters.

Due to a recent clarification in the core inline documentation standards, HTML tags are no longer allowed in DocBlock summaries as they wreak havoc on displaying pages in the official Code Reference. See #30473.

See #30469.

#19 @DrewAPicture
10 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

@DrewAPicture
10 years ago

#20 @DrewAPicture
10 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 30720:

Backtick-escape three sets of HTML entities used in DocBlock descriptions in wp-includes/kses.php.

Without the escaping, the Code Reference/browser may inadvertently attempt to convert and display entities.

Fixes #30473.

#21 @DrewAPicture
10 years ago

In 30721:

Remove some now-unnecessary double quotes around HTML entities used in DocBlock comments.

See #30473.

#22 @TobiasBg
10 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

For [30721], can I suggest to wrap the individual entities in `, to not include the commas and the "to"?

* `AT&amp;T`, `&#00058;` to `&#58;`, `&#XYZZY;` to `&amp;#XYZZY;` and so on.

#23 @DrewAPicture
10 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 30726:

Only backtick-escape individual HTML entities in the DocBlock for wp_kses_normalize_entities().

Props TobiasBg.
Fixes #30473.

#24 @SergeyBiryukov
10 years ago

In 30727:

Fix a typo in [30546].

see #30473.

#25 @kpdesign
10 years ago

#29515 was marked as a duplicate.

Note: See TracTickets for help on using tickets.