Document the pitfalls of deviating from naming convention for hook_theme()'s 'function' and 'template' keys

I just spent a lot of time struggling with hook_theme with following syntax:

function taxonomy_sites_theme($existing, $type, $theme, $path) {
  return array(
      'taxonomy_sites_frontpage' => array(
        'arguments' => array('taxonomy' => NULL, 'term' => NULL),
        'template' => 'master',
        'type' => 'theme',
        ),
      );
}

Note that template file is supposed to be master.tpl.php and theme is called taxonomy_sites_frontpage. That is incorrect. Due to the fact how theme system discovery works, Drupal will never find your master.tpl.php file in your themes.

Why? Because 'taxonomy_sites_frontpage' != 'master'. They need to be equal in order to have this functionality.

There are two options:
1) It's a bug. - I am not sure about that
2) It needs to be stressed in hook_theme() documentation so people know exactly what's going on.

I am leaning towards 2