The API docs for these APIs was moved to language.module (and the APIs were renamed) in #1301040: Move language listing functionality from locale.module to a new language.module. The locale.api.php file has these leftover items though. It is a very straightforward change, so RTBC-ing right away.

These are all documented proper in http://api.drupal.org/api/drupal/core%21modules%21language%21language.ap... the docs removed in this patch are duplicate and obsolete.

CommentFileSizeAuthor
#13 system-language-hooks.patch12.29 KBGábor Hojtsy
PASSED: [[SimpleTest]]: [MySQL] 38,306 pass(es). View
#5 locale-api-php-is-not-good.patch14.21 KBGábor Hojtsy
PASSED: [[SimpleTest]]: [MySQL] 35,111 pass(es). View
#3 merge-locale-language-api-php.patch14.15 KBGábor Hojtsy
PASSED: [[SimpleTest]]: [MySQL] 35,101 pass(es). View
remove-obsolete-hook-docs.patch1.51 KBGábor Hojtsy
PASSED: [[SimpleTest]]: [MySQL] 35,120 pass(es). View
Members fund testing for the Drupal project. Drupal Association Learn more

Comments

Gábor Hojtsy’s picture

Issue tags: +sprint
webchick’s picture

Component: locale.module » documentation

Switching components so this gets onto Jennifer's radar.

Gábor Hojtsy’s picture

Title: Remove API docs for APIs moved to language module » Merge locale.api.php and language.api.php
FileSize
14.15 KB
PASSED: [[SimpleTest]]: [MySQL] 35,101 pass(es). View

@webchick: thanks!

In fact, we should not only remove the parts that were already moved to language.api.php but move the rest too. language.module is the base language management UI so language.api.php is the place for all base language API docs. The hooks documented here are not in fact part of either language module or locale module, they are part of the language base system (housed on bootstrap.inc and language.inc), but we don't really have a better place to document these hooks.

Since there are no locale hooks documented whatsoever, this effectively removes locale.api.php.

Note that I made no changes to the docs in any way. I just copy-pasted. The hooks are already all hook_language_*().

jhodgdon’s picture

Status: Reviewed & tested by the community » Needs work

Hmm. Normally we only put hooks in a modules/xyz/xyz.api.php if the hooks are actually part of that module.

Other hooks should go into modules/system somewhere by convention. Perhaps we need a modules/system/language.api.php file to house hooks that are not really part of language.module but really part of the base language system? Otherwise if there are just a few, they can go into system.api.php itself.

Gábor Hojtsy’s picture

Title: Merge locale.api.php and language.api.php » Nothing on locale.api.php belongs there
Status: Needs work » Needs review
FileSize
14.21 KB
PASSED: [[SimpleTest]]: [MySQL] 35,111 pass(es). View

Ok retitled for the base problem of the issue :) So we have these in locale.api.php:

function hook_language_init() {
}
function hook_language_switch_links_alter(array &$links, $type, $path) {
}
function hook_language_types_info() {
}
function hook_language_types_info_alter(array &$language_types) {
}
function hook_language_negotiation_info() {
}
function hook_language_negotiation_info_alter(array &$negotiation_info) {
}
function hook_language_fallback_candidates_alter(array &$fallback_candidates) {
}

All these are invoked only from the base include files of bootstrap.inc and language.inc, in order:

core/includes/bootstrap.inc:    bootstrap_invoke_all('language_init');
core/includes/language.inc:        drupal_alter('language_switch_links', $result, $type, $path);
core/includes/language.inc:    $language_types = module_invoke_all('language_types_info');
core/includes/language.inc:    drupal_alter('language_types_info', $language_types);
core/includes/language.inc:    $negotiation_info = module_invoke_all('language_negotiation_info');
core/includes/language.inc:     drupal_alter('language_negotiation_info', $negotiation_info);
core/includes/language.inc:    drupal_alter('language_fallback_candidates', $fallback_candidates);

Therefore we can conclude all those hooks are defined by the base system as per your grouping and should go to system.module. I think these are numerous enough to warrant their own file.

The rest of the hooks documented in locale.api.php are all hook_locale_language_*() which since been all moved to language.api.php and renamed to hook_language_*(). All of those are new to D8.

This makes locale.api.php disappear with items removed and moving to language.api.php in system module. I *did not* make any changes to the docs themselves. Just modified the @file header to properly explain what hooks are these.

Gábor Hojtsy’s picture

Title: Nothing on locale.api.php belongs there » Nothing in locale.api.php belongs there
jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

That sounds like the right fix. I'll get it committed.

catch’s picture

For a follow-up maybe since api module scans these files wherever they are, could we not do something like includes/api and put various *.api.php files in there? That would then cover any hook that's not invoked by a module, and we could keep system module out of it.

jhodgdon’s picture

I suppose we could move a lot of the hooks that are in modules/system/*.api.php into that proposed includes directory -- I think most of the ones even in system.api.php are not really system.module functionality. Sounds like a reasonable idea, but a separate issue?

jhodgdon’s picture

Status: Reviewed & tested by the community » Fixed
Issue tags: -sprint

Meanwhile, I've committed this patch. I guess it's 8.x only...

Gábor Hojtsy’s picture

Version: 8.x-dev » 7.x-dev
Status: Fixed » Patch (to be ported)

Thanks, http://api.drupal.org/api/drupal/modules%21locale%21locale.api.php/7 also has lots of system level hooks documented. The last two are D7 hooks (the first before the last one was removed entirely in D8 and the last one was replaced by more general hooks). So I think this would apply to D7 if we want to clean up API docs placement there too. Feel free to move back to D8 fixed if that is not the case.

jhodgdon’s picture

Sounds like a good plan. A straight backport of the above patch wouldn't work, but yes we could move a bunch of the hooks into a new file like in the d8 patch.

Gábor Hojtsy’s picture

Status: Patch (to be ported) » Needs review
FileSize
12.29 KB
PASSED: [[SimpleTest]]: [MySQL] 38,306 pass(es). View

Ok, here is a D7 version. Because D7 does have two hooks from locale module, locale.api.php is kept with those.

jhodgdon’s picture

Status: Needs review » Fixed

Looks good to me. Committed to 7.x

Automatically closed -- issue fixed for 2 weeks with no activity.