Add Editor Documentation Functions URL for theme-defined functions

[GamajoTech]

Currently, functions that are called within template files shown on the editor are included in the list of functions that you can try and lookup documentation for.

(The $ignore_functions array only seems to be for functions defined, not called, in a file.)

As the ​http://api.wordpress.org/core/handbook/1.0/?function=... seems to be hard-coded in, it's not possible for themes to overwrite it for functions they've defined.

Is it possible to allow themes to define where the documentation lookup should be for their own functions?

[GaryJ]

First draft.

[GaryJ]

First attempt at adding a filter here.

• esc_url() may or may not be the right escape here.
• The filter name may need to be a less general name if the plugin editor can't be filtered with the same signature.
• The current theme and file path are passed as arguments, so the URL can be changed conditionally.
• It may be that passing the full path as the $file is not helpful, and can perhaps be trimmed down to be a relative path from the theme folder.

Themes could now filter the URL as per normal:

add_filter( 'documentation_url', 'child_documentation_url', 10, 3 );
/**
 * Filter the function documentation URL in theme editor.
 *
 * @param string $url
 * @param string $theme Name of the theme
 * @param string $file full path of the file being edited
 * @return string
 */
function child_documentation_url( $url, $theme, $file ) {

	if ( 'My Awesome Theme' != $theme )
		return $url;

	return 'http://my.example.com/?theme= ' . $theme . '&function=';

}

It would then be up to the script at my.example.com to check the function name against a list of known functions for that theme (or at least ones they want to provide documentation for - could even provide more detailed documentation for WP functions) and redirect to their own documentation, or redirect back to api.wordpress.org/code/handbook/1.0/?function= accordingly.

[chriscct7]

Refresh to adjust link to https

[swissspidy]

I guess this needs a new patch for the theme and plugin editors, including proper filter docs.

Probably a better filter name than documentation_url as well, maybe file_editor_documentation_url.

[exthilion]

Apply @GaryJ's original patch to theme and plugin editor

[exthilion]

I'm new to submitting patches here, so please forgive me if this isn't the right way to approach this.
Per the patch above by @GaryJ

<?php
add_filter( 'file_editor_documentation_url', 'child_documentation_url', 10, 3 );
/**
 * Filter the function documentation URL in theme editor.
 *
 * @param string $url a default url if $provider doesn't provide a custom url
 * @param string $provider Name of the theme or plugin
 * @param string $file full path of the file being edited
 * @return string
 */
function child_documentation_url( $url, $provider, $file ) {
        // Check if $provider is handled by this filter. If not, use default.
        if ( 'My Awesome Theme or Plugin' != $provider )
                return $url;
        // Provide some kind of logic here to generate correct documentation url for $file.
        return 'http://my.example.com/?theme= ' . $provider . '&function=';
}

Seems like a trivial change, but I am also unsure of what @swissspidy means by proper docs.

[exthilion]

https links by default, per @chriscct7

[swissspidy]

@exthilion Thanks for the patch.

As per our ​inline documentation standards, each hook and filter in core needs inline documentation, similar to how you documented child_documentation_url in your example above.

[DrewAPicture]

Assigning to mark the good-first-bug as "claimed".

See filter-https.diff​

[desrosj]

Just did some testing, and looks like this issue still exists today.

Personally, I think any hooks that help developers provide better documentation are great additions. Though I definitely don't like the idea of someone replacing a php.net or wordpress.org documentation URL with their own, there could be scenarios where this is beneficial.

I don't think filter-https.diff​ is the right approach. There is one button output to navigate the user to the correct location based on the option selected. This patch would specify one URL for all functions if filtered.

I think a better solution would be to change the <option> tag's value attribute to a full URL when someone wishes to override or supply their own documentation URL. The JavaScript should then be updated to use the value of the selected item if it is determined to be a URL.

@exthilion I know that it's been a long time. But would you be interested in creating a patch?