Document the 'pages' key in hook_block_info()

Sounds like a good thing to document. Documentation of 'pages' should probably say that it can be a string with the paths, or PHP code, depending on the value of 'visibility'.

And while we're at it, this whole doc block's list formatting could be updated to current standards (not using '' around the array element names):
http://drupal.org/node/1354#lists

I made the suggested changes (for 'pages' and for the array element names).

Here are two patches - one for 8.x and one for 7.x

It's my first core patch (doc or otherwise) - please be gentle with me :-)

Guess I needed to open a separate issue for 7.x - will do so

I'll make that change (for PHP code) and re-roll the patch.

I've also opened #1503614: Document the 'pages' key in hook_block_info() for the 7.x backport.

Here's the update with the PHP code addition

Dang it. Typo - fixed

So we should :-)

The docs look good! A minor grammatical nitpick: "which" should be "that" (in "A string which contains one or...") (bonus points if you fix which/that in the text above too -- you use "which" only if it's after a comma).

Also, I think we should also document here that you can use * as a wildcard in the paths?

It's a good nit to pick, though also one that I often ignore - but 'which' and 'that' do have different use cases, which are worth remembering.

Much better... Still a little concerned about wording:

...
+ *     PHP code when 'visibility' is set to BLOCK_VISIBILITY_PHP. Paths may
+ *     include the wildcard extension '*' (e.g. 'node/*' to designate
+ *     all pages having paths beginning with 'node/'), or '<front>' to
+ *     designate the site front-page. For BLOCK_VISIBILITY_PHP,
...

How about just this for that sentence:

Paths may use * as a wildcard (matching any number of characters); designates the site's front page.

Gotcha. And done...

Why is wrapping < 80 a problem? No lines are > 80; neither are any abnormally short or broken at odd places.

Everything should wrap as close to 80 characters as possible (including leading white space).
http://drupal.org/node/1354#general (last bullet point in that section)

Okay, thanks. Try this one - I think everything is wrapped as near to 80 as I could get it.

Grrr - annoys me that I missed that. Thanks, tstoeckler. This is good to go now, I trust :-)

Committed to 8.x. Thanks!!

Apparently needs to be rerolled before it will apply to 7.x.

No prob - will do it later on today.

re-rolled for 7.x

RTBC at 3/28 Long beach Drupal LA meetup
works well

Thanks - committed to 7.x.

The docs are in code in D6, just not in Drupal Core. Moving to Documentation project (that is where the files are, in the Documentation project git repo, under developer/hooks). Patch welcome. :)

Here's a patch for 6.x. I only made the changes to document 'pages.' I made no attempt to backport the other changes in 7.x and 8.x

The indentation is not correct there, but other than that it looks fine, and I agree with the idea of only fixing the 'pages' documentation.

When you're right, you're right.
Here's another patch...

I read through the documentation in #38 (for 'pages') and it is clear to me but I don't know where to apply the patch.

Didn't mean to put it back to active.

It took me a little while to find it - it's part of the Documentation project

Yes, Documentation project (hence why this issue was moved to that project. :) ).

Thanks! I've committed this to the D6 docs project. Moving issue back to core for posterity.