The Classy base theme in Drupal 8 contains almost every core module template. These templates are being organized in a themer-centric way, rather than just mimicking the module organization scheme. While this will certainly make some aspects of theming more intuitive, this organization may also create a disconnect between the templates in the base-theme and their associated core templates in the modules directory. Further complicating things, the exact use of some template files is not immediately obvious and needs more explanation.
Every template in Classy should include a meaningful description of what it's used for, a reference back to the original template in its associated core module, and an example link to where its output can be seen.
- Agree on a standard format for this documentation in template files.
- Add it to all the files.