The API documentation for hook_requirements() (found at http://api.drupal.org/api/drupal/modules--system--system.api.php/functio...) says:

This hook has two closely related uses, determined by the $phase argument: checking installation requirements ($phase == 'install') and status reporting ($phase == 'runtime').

Then later on it lists THREE phases, not two:

Parameters

$phase The phase in which requirements are checked:
    * install: The module is being installed.
    * update: The module is enabled and update.php is run.
    * runtime: The runtime requirements are being checked and shown on the status report page.

The example shown on the API page, taken from modules/system/system.api.php, line 2806, shows the code parsing for three phases.

I don't recall an 'update' phase in Drupal 6, so maybe this is a change between 6 and 7. Although, there is only one version of the hook_requirements() API page which covers Drupal versions 5 through 7. Regardless, the documentation should be corrected/clarified. I think, but am not sure, that the 'update' phase was added by http://drupal.org/node/228860 (see http://drupal.org/node/228860#comment-2945772 for a statement to this effect).

Perhaps this should also be added to the documentation for converting modules from D6 to D7 ? http://drupal.org/update/modules/6/7

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

arianek’s picture

Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Correction/Clarification » documentation

moving to core docs queue

jhodgdon’s picture

Title: hook_requirements API documentation needs correction » hook_requirements API documentation needs doc on 'update' phase

There are actually different pages for the d6 and d5 functions. It's just that the API module currently has a bug and the navigation is not being shown between the versions. If you start from the d6 API home and search, you'll find the d6 version.

That aside, good catch! The d7 version does need to be fixed. I don't think we need doc on the Module update 6->7 page though, since that page is primarily to document changes in API that will break your module if you don't fix them, and this is an API addition, not really a change.

Anonymous’s picture

Version: 7.x-dev » 8.x-dev
Status: Active » Needs review
FileSize
714 bytes

I changed the wording at the top of the doc block for hook_requirements. I think this was the only change that was needed.

jhodgdon’s picture

Status: Needs review » Needs work

I think a comma is needed here, and the paragraph should be wrapped as close to 80 characters as possible. With your patch, the paragraph would read:

* This hook has three closely related uses, determined by the $phase argument:
* checking installation requirements ($phase == 'install')
* checking update requirements ($phase == 'update')
* and status reporting ($phase == 'runtime').

So there needs to be a comma after the first and second lines in the above, and then they need to be wrapped to nearly 80 character line length. Other than that, the change looks correct to me. The alternative would be to make it into a bullet list. Either way is fine.

Anonymous’s picture

Assigned: Unassigned » linclark

Thanks for the review! I'm going to be showing 3 people how to roll patches tomorrow, so I'm going to have one of them do the update to this.

guidocecilio’s picture

Version: 8.x-dev » 7.x-dev
Assigned: linclark » guidocecilio
Status: Needs work » Needs review
FileSize
905 bytes

I changed it using the second alternative explained in comment #4.

jhodgdon’s picture

Version: 7.x-dev » 8.x-dev
Status: Needs review » Needs work

The bullet list approach is fine, and the patch is almost correct. But one small thing: the list needs to follow our list guidelines:
http://drupal.org/node/1354#lists
"Each list item starts with the key, followed by a colon, followed by a space, followed by the key description. The key description starts with a capital letter and ends with a period. If the list has no keys, start each list item with a capital letter and end with a period."

So the list items each need to start with a capital letter. Thanks!

One other thing: we need to leave the version at 8.x, commit to 8.x first, and then to 7.x. The reason being that we don't want older versions of Drupal to have fixes that the newer versions don't already have.

guidocecilio’s picture

Status: Needs work » Needs review
FileSize
905 bytes

List items have been changed starting with a capital letter using the correct formatting convention.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Excellent, thanks! Hope you come back and make another patch soon. :)

Dries’s picture

Status: Reviewed & tested by the community » Fixed

Committed to 7.x and 8.x. Thanks!

Status: Fixed » Closed (fixed)

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