Improve documentation for format_for_editor()

[swissspidy]

format_for_editor() has an optional $default_editor parameter that I think is either passed 'html' or 'text'. It's totally not documented and could need some love.

See also the the_editor_content filter where format_for_editor() is applied to. $default_editor needs to be documented there as well.

See the ​PHP documentation standards for formatting details.

[AramZS]

Making a note here that the default value is not guaranteed to this function, but is depending on either the parent's call or the user's settings. This is what I think I've found, and it is sort of confusing.

_WP_Editors()::parse_settings() enforces the defaults passed to format_for_editor() and specifies an empty default.

_WP_Editors()::editor() uses wp_default_editor() to set and empty value for $default_editor to either 'tinymce' or 'html' depending on user permissions and then the settings for the user via get_user_setting('editor', 'tinymce');. The allowed values there are 'tinymce', 'html' and 'test' and that is filtered by apply_filters( 'wp_default_editor', $r );

If nothing is passed, the default is called. If anything other than 'html' is set by either method, WordPress will change the value to tinymce.

Theoretically, at this point, format_for_editor should be hooked to the_editor_content where it will receive both the content that gets filtered and the $default_editor value (not assured, but likely one of the two above options). The back-compat code seems to indicate that is the case:

		// Back-compat for the `htmledit_pre` and `richedit_pre` filters
		if ( 'html' === $default_editor && has_filter( 'htmledit_pre' ) ) {
			// TODO: needs _deprecated_filter(), use _deprecated_function() as substitute for now
			_deprecated_function( 'add_filter( htmledit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
			$content = apply_filters( 'htmledit_pre', $content );
		} elseif ( 'tinymce' === $default_editor && has_filter( 'richedit_pre' ) ) {
			_deprecated_function( 'add_filter( richedit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
			$content = apply_filters( 'richedit_pre', $content );
		}

Notably format_for_editor is only hooked to the the_editor_content filter in a situation where the user is allowed to use TinyMCE. Which can be the case for either html or tinymce. But, if, let's say, the user can only see the_editor_content in HTML mode (because, for example, TinyMCE is disallowed), the filter is never added:

		if ( self::$this_tinymce ) {
			add_filter( 'the_editor_content', 'format_for_editor', 10, 2 );
		}

Which means that $default_editor will (in practice) only ever take html or tinymce. Developers who turn off TinyMCE (even if they're using some other wysiwyg) and users without permission to use it will never see the format_for_editor filter fire. The only other case where this would apply would be if some plugin or theme is calling this function themselves and feeding in a different value? Is that an intended use? I don't know if this should matter for documenting, but I thought I'd note here that this might not be the intended execution, as indicated by the rest of the code. It's also weird, because it means that you can only filter the_editor_content if tinymce is enabled, though it can effect both html and tinymce modes.

[AramZS]

First pass at making documentation consistent with current behavior.

[AramZS]

I've patched this to make the inline documentation significantly clearer. However, I'm not entirely sure the filters here are working as expected, but that would be a whole other ticket.

[swissspidy]

34866.2.patch​ is an updated patch, unifying and properly aligning the docs.

[swissspidy]

In 35904:

Docs: Improve documentation for format_for_editor() and the 'the_editor_content' filter it is hooked to.

Props AramZS for initial patch.
Fixes #34866.