Page handler nomenclature is confusing

[mrclay]

The PHPDoc for elgg_register_page_handler is clearest: "Registers a page handler for a particular identifier"; i.e. "discussion" is the identifier and "discussion_page_handler" is the handler (function), but confusingly the variable name $handler is used in many places to mean identifier.

I was surprised to find in page_handler(), route/$handler actually triggered route/discussion, not route/discussion_page_handler. Unfortunately, the identifier is passed to the hook handler under the key 'handler', so changing that could break BC, but renaming the local vars would help. What is also confusing is how the route hook is triggered passing $params in, but in your handler this is actually $returnvalue, not $params.

The "route" hook trigger should also probably be mentioned on the Engine/Controllers/PageHandler wiki page.

[ewinslow]

Care to submit a PR?