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?

[dontfeedthecode]

Refactored approach to handling the doc URL overriding for theme/plugin editing.

[dontfeedthecode]

I've taken a stab at refactoring this as per the suggestion from @desrosj and have provided a patch.

https://core.trac.wordpress.org/attachment/ticket/14808/doc-override.diff

Below are usage examples, the patch provides two filters (one for theme links, one for plugin links to make a clear distinction between the two) and allows the user to override links down to an individual function level.

The onchange event for the button does a simple check to see if the option value starts with http or https, opens that link rather than the default if provided and falls back to the original if not. I'd like to have moved this JS out of the inline event tag and into a script block to allow for a more robust solution, e.g. using a try/catch with URL(), as this would be quite lengthy.

<?php
/**
 * Filter the function documentation URL in either the theme or plugin editor.
 *
 * @param string $function Name of the selected function.
 * @param string $file Full path of the file being edited.
 * @param string $theme Director name of the theme being edited.
 * @return string
 */
function override_theme_documentation_links( $function, $file, $theme ) {

        // Ignore for anything but our test theme.
        if ( 'test-theme' !== $theme ) {
                return $function;
        }

        // Example 1: Override documentation URL's for specific functions.
        if ( 'get_header' === $function ) {
                return 'https://mysite.com/different-docs?function=' . $function;
        }

        // Example 2: Override documentation URL's for all functions within a specific file.
        if ( str_contains( $file, 'header.php' ) ) {
                return 'https://mysite.com/header-docs?function=' . $function;
        }

        // Example 3: Override documentation URL's for all functions for theme.
        return 'https://mysite.com/docs?function=' . $function;
}

add_filter( 'theme_editor_documentation_url', 'override_theme_documentation_links', 10, 3 );

/**
 * Filter the function documentation URL in the plugin editor.
 *
 * @param string $function Name of the selected function.
 * @param string $file Full path of the file being edited.
 * @param string $name Name of the plugin being edited.
 * @return string
 */
function override_plugin_documentation_links( $function, $file, $plugin ) {

        // Ignore for anything but our test plugin.
        if ( 'hello.php' !== $plugin ) {
                return $function;
        }

        // Example 1: Override documentation URL's for all functions for plugin.
        return 'https://mysite.com/plugin-docs?function=' . $function;
}

add_filter( 'plugin_editor_documentation_url', 'override_plugin_documentation_links', 10, 3 );

As per the Trac ticket, I've refactored a previous approach to allow for documentation URL's to be overridden within the theme and plugin editor. The previous approach had some limitations, this approach provides two new filters (one for theme, another for plugins) that allow documentation links to be overridden by theme, plugin, file or individual function.

Trac ticket: https://core.trac.wordpress.org/ticket/14808

Example usage:

`<?php
/

• Filter the function documentation URL in either the theme or plugin editor. *
• @param string $function Name of the selected function.
• @param string $file Full path of the file being edited.
• @param string $theme Director name of the theme being edited.
• @return string */

function override_theme_documentation_links( $function, $file, $theme ) {

Ignore for anything but our test theme.
if ( 'test-theme' !== $theme ) {

return $function;

}

Example 1: Override documentation URL's for specific functions.
if ( 'get_header' === $function ) {

return '​https://mysite.com/different-docs?function=' . $function;

}

Example 2: Override documentation URL's for all functions within a specific file.
if ( str_contains( $file, 'header.php' ) ) {

return '​https://mysite.com/header-docs?function=' . $function;

}

Example 3: Override documentation URL's for all functions for theme.
return '​https://mysite.com/docs?function=' . $function;

}

add_filter( 'theme_editor_documentation_url', 'override_theme_documentation_links', 10, 3 );

/

• Filter the function documentation URL in the plugin editor. *
• @param string $function Name of the selected function.
• @param string $file Full path of the file being edited.
• @param string $name Name of the plugin being edited.
• @return string */

function override_plugin_documentation_links( $function, $file, $plugin ) {

Ignore for anything but our test plugin.
if ( 'hello.php' !== $plugin ) {

return $function;

}

Example 1: Override documentation URL's for all functions for plugin.
return '​https://mysite.com/plugin-docs?function=' . $function;

}

add_filter( 'plugin_editor_documentation_url', 'override_plugin_documentation_links', 10, 3 );`

[adamsilverstein]

Having worked on this ticket with contributors at WordCamp Asia I'm going to self-assign for further review.