In an effort to convert as much of Drupal's theme_* functions to tpl.php files as possible, I went through and did the forum module's theme functions (I picked those because I knew they'd be more difficult than some other modules). One thing I encountered is that this new system has no documentation standard for tpl.php files. I propose the following items: We should create a themes.php in contributions/docs/developer that contains definitions for theme_* functions that are being converted (or are new and will never have had a theme_* function before). Everything in this file should be @ingroup themeable. It would contain the full documentation for the theme function, including the @params. All .tpl.php files should contain a Doxy syntax @file directive that summarizes the template and lists variables that are commonly available. This list does not need to be exhaustive but it should include the most important variables, at a minimum. It should contain an @see to the template_preprocess function, if it exists, and a @see to the theme_HOOK function in the contrib docs. The template_preprocess_HOOK function should contain a @see to the theme_ function and a list of the arguments (mostly for reference while looking at the function; since the argument to that function will always just be &$variables, it's nice to get a look at what data is coming in). Both of the above should also contain an @see to the .tpl.php file -- however, in api.module, currently @see doesn't work on files. I think api.module could probably be modified to rectify this for us, or another method of referencing the file could work. Here are some examples. Note that I did these before I thought about a theme.php so these aren't updated for that yet, but I intend to. forum_list.tpl.php: <?php // $Id$ /** * @file forum_list.tpl.php * Default theme implementation to display a list of forums. * * Available variables: * - $forums: An array of forums to display. * * Each $forum in $forums contains: * - $forum->is_container: Is TRUE if the forum can contain other forums. Is * FALSE if the forum can contain only topics. * - $forum->depth: How deep the forum is in the current hierarchy. * - $forum->name: The name of the forum. * - $forum->link: The URL to link to this forum. * - $forum->description: The description of this forum. * - $forum->new_topics: True if the forum contains unread posts. * - $forum->new_url: A URL to the forum's unread posts. * - $forum->new_text: Text for the above URL which tells how many new posts. * - $forum->old_topics: A count of posts that have already been read. * - $forum->num_posts: The total number of posts in the forum. * - $forum->last_reply: Text representing the last time a forum was posted or * commented in. * * @see template_preprocess_forum_list() */ ?> Example in api.module: http://drupal.logrus.com/api/file/drupal/modules/forum/forum_list.tpl.php/he... /** * Process variables for forum_display.tpl.php * * The $variables array contains the following arguments: * - $forums * - $topics * - $parents * - $tid * - $sortby * - $forum_per_page * * @see forum_display.tpl.php */ function template_preprocess_forum_display(&$variables) { Example in api.module: http://drupal.logrus.com/api/function/template_preprocess_forum_list/head