hook_page_attachments() and _alter() hooks have incorrect docs

Well, if you look at where the hook is invoked, actually what happens is:

a) hook_page_attachments() is called on each module that implements it. Starting with an empty array, the hook is invoked on each module, passing the result to the next module, to build up an array of attachments.

b) hook_page_attachments_alter() is then called on each module or theme that implements it. What is passed in is the result of hook_page_attachments().

c) If either of these hooks adds anything but #attached and #post_render_cache elements to the array, and exception is thrown.

So both of these hooks have incorrect documentation, and neither one mentions (c). The docs for both hooks need an update:

(1) Rather than $page they should call the parameter $attachments, and document that you should add elements to #attached and #post_render_cache elements only.

(2) In the alter hook docs, this sentence should be removed:

If you want to alter the attachments added by other modules or if your module depends on the elements of other modules, use hook_page_attachments_alter() instead, which runs after this hook.

This should be a good project for a novice contributor...

Thanks @jhodgdon for earlier helping me on irc.

Thanks for the patch! It's a great start... A few things to address:

a) In both hooks:

- * @param array &$page
+ * @param array &$attachments
  *   An empty renderable array representing the page.

I think we need to change the description here as well as the name of the parameter.

b) In both hooks:

+ * If you try to attach anything but #attached and #post_render_cache to the array
+ * an exception is thrown.

I don't think we should use the word "attach" here for the array? How about "If you try to add anything..."?

The rest looks great!

@jhodgdon, modified patch as directed by you.Thanks

Looks good to me! I guess... Maybe in the _alter() hook, should we change the @param description to say:

Array of all attachments provided by hook_page_attachments() implementations.

?? Because it's an alter hook...

@jhodgdon,didn't noticed that earlier.Thanks

Great, thanks!

Should this use @throws?

I don't think so. @throws is usually for "This function itself throws an exception", not for "If you put the wrong thing into your hook implementation, the function that invokes this hook will throw an exception", right?

Probably...

Yep no @throws. Documentation is not frozen during beta. Committed 17c9a2a and pushed to 8.0.x. Thanks!