Make WordPress Core

Opened 14 years ago

Last modified 22 months ago

#14808 assigned enhancement

Add Editor Documentation Functions URL for theme-defined functions

Reported by: gamajotech's profile GamajoTech Owned by: exthilion's profile exthilion
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: General Keywords: good-first-bug has-patch needs-refresh changes-requested
Focuses: administration Cc:

Description

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?

Attachments (3)

14808.diff (1.2 KB) - added by GaryJ 13 years ago.
First draft.
filter.diff (2.8 KB) - added by exthilion 8 years ago.
Apply @GaryJ's original patch to theme and plugin editor
filter-https.diff (2.8 KB) - added by exthilion 8 years ago.
https links by default, per @chriscct7

Download all attachments as: .zip

Change History (16)

#1 @nacin
14 years ago

  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to Future Release

@GaryJ
13 years ago

First draft.

#2 @GaryJ
13 years ago

  • Cc gary@… added

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.

#3 @defries
13 years ago

  • Cc remkus@… added

#4 @SergeyBiryukov
13 years ago

  • Keywords has-patch added; needs-patch removed

#5 @chriscct7
10 years ago

  • Keywords needs-refresh added

Refresh to adjust link to https

#6 @iseulde
9 years ago

  • Component changed from Editor to Themes

#7 @swissspidy
8 years ago

  • Keywords good-first-bug needs-patch added; has-patch needs-refresh removed

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
8 years ago

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

#8 @exthilion
8 years ago

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
 * @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 ) {

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

        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.

Version 0, edited 8 years ago by exthilion (next)

@exthilion
8 years ago

https links by default, per @chriscct7

#9 @swissspidy
8 years ago

@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.

#10 @DrewAPicture
8 years ago

  • Keywords has-patch added; needs-patch removed
  • Owner set to exthilion
  • Status changed from new to assigned

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

See filter-https.diff

#11 @isabel_brison
4 years ago

  • Keywords needs-refresh added

#12 @desrosj
22 months ago

  • Keywords changes-requested added
  • Milestone set to Future Release

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?

#13 @desrosj
22 months ago

  • Component changed from Themes to General
  • Focuses administration added
Note: See TracTickets for help on using tickets.