docs for hook_toolbar() are very confusing

Problem/Motivation

 * The toolbar provides a construct called a 'tray'. The tray is a container
 * for content. The tray may be associated with a toggle in the administration
 * bar. The toggle shows or hides the tray and is optimized for small and
 * large screens. To create this association, hook_toolbar() returns one or
 * more render elements of type 'toolbar_item', containing the toggle and tray
 * elements in its 'tab' and 'tray' properties.

I find this incomprehensible.

'provides a construct'???

Having poked around a bit, I think it means that a toolbar_item is composed of:

- the 'tab' which is the item you see in the toolbar all the time
- optionally, the 'tray' which is the submenu that opens when you click the tab item.

It doesn't help that neither of these words are terribly able, as the tabs don't look like tabs, and if you have a wide enough screen, the tray doesn't look like a tray.

Steps to reproduce

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet