Problem/Motivation
There is currently no real documentation on how to utilize the new Dialog/Modal APIs properly.
The only thing that currently exists is the rather vague Ajax API group topic which includes some of the dialog/modal response commands in a table at the bottom and a couple change records that are rather terse with examples:
https://www.drupal.org/node/1852224
https://www.drupal.org/node/1989646
Suffice it to say, you're kind of SOL if you weren't involved or familiar with the issues that added dialog/modal support into core.
The only reprise is to start digging around the internal core/contrib code (both PHP and JavaScript) to try and reverse engineer how it's "supposed" to work. This can be made worse if you're only a novice with JavaScript and don't understand how the dialog/modal "magic" actually happens.
Proposed resolution
Create a "Dialog/Modal API" documentation topic.
Remaining tasks
- Create patch
User interface changes
None
API changes
None
Data model changes
None